GNU Emacs Lisp Reference Manual

For Emacs Version 26.1

Revision 3.1, October 2014

by Bil Lewis, Dan LaLiberte, Richard Stallman,
the GNU Manual Group, et al.

This is the GNU Emacs Lisp Reference Manual corresponding to Emacs version 26.1.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “GNU General Public License,” with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

Published by the Free Software Foundation
51 Franklin St, Fifth Floor
Boston, MA 02110-1301
USA
ISBN 1-882114-74-4

Cover art by Etienne Suvasa.

Emacs Lisp

This is the GNU Emacs Lisp Reference Manual corresponding to Emacs version 26.1.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “GNU General Public License,” with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled “GNU Free Documentation License.”

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”


1 イントロダクション		イントロダクションと使用される慣習。
2 Lispのデータ型		Emacs Lispでのオブジェクトのデータタイプ。
3 数値		数値と算術関数。
4 文字列と文字		文字列とそれらを処理する関数。
5 リスト		リスト、コンスセルと関連する関数。
6 シーケンス、配列、ベクター		リスト、文字列、ベクターはシーケンスと呼ばれる。特定の関数は任意の種類のシーケンスに機能する。ここではベクターの説明も行う。
7 Records		Compound objects with programmer-defined types.
8 ハッシュテーブル		非常に高速な照会テーブル。
9 シンボル		名前を一意に表すシンボル。

10 評価		Lisp式が評価される方法。
11 制御構造		条件文、ループ、非ローカル脱出。
12 変数		プログラムで値を表すためにシンボルを使用する。
13 関数		関数とは別の関数から呼び出せるLispプログラムである。
14 マクロ		マクロとはLisp言語を拡張する手段である。
15 カスタマイズ設定		変数やフェイスをカスタマイズ可能にする。

16 ロード		LispコードのファイルをLispに読み込む。
17 バイトコンパイル		プログラム実行を高速にするコンパイル。
18 Lispプログラムのデバッグ		Lispプログラムのデバッグのためのツールとヒント。

19 Lispオブジェクトの読み取りとプリント		Lispオブジェクトからテキストへの変換と逆変換。
20 ミニバッファー		入力を読み取るためにミニバッファーを使用する。
21 コマンドループ		エディターコマンドループが機能する方法と、そのサブルーチンを呼び出す方法。
22 キーマップ		キーをコマンドにバインドするための定義。
23 メジャーモードとマイナーモード		メジャーモードとマイナーモードの定義。
24 ドキュメント		ドキュメント文字列の記述と使用。

25 ファイル		ファイルへのアクセス。
26 バックアップと自動保存		バックアップファイルト自動保存ファイルの作成方法の制御。
27 バッファー		バッファーオブジェクトの作成と使用。
28 ウィンドウ		ウィンドウの操作とバッファーの表示。
29 フレーム		システムレベルウィンドウを複数作成する。
30 ポジション		バッファー位置と移動関数。
31 マーカー		マーカーは位置を表し、テキスト変更時に自動的に更新される。

32 テキスト		バッファー内のテキストの調査と変更。
33 非ASCII文字		バッファーと文字列内の非ASCIIテキスト。
34 検索とマッチング		バッファー内の文字列や正規表現の検索。
35 構文テーブル		単語やリストの解析を制御する構文テーブル。
36 abbrevとabbrev展開		Abbrevモードが機能する方法と、そのデータ構造。

37 Threads		Concurrency in Emacs Lisp.
38 プロセス		サブプロセスの実行と対話。
39 Emacsのディスプレー表示		スクリーン表示を制御するための機能。
40 オペレーティングシステムのインターフェース		ユーザーID、システムタイプ、環境変数、その他類似項目の取得。

41 配布用 Lispコードの準備		配布用にLispコードを準備する。
Appendices
Appendix A Emacs 25 Antinews		Info for users downgrading to Emacs 25.
Appendix B GNU Free Documentation License		このドキュメントのライセンス。
Appendix C GNU General Public License		GNU Emacsの複製と変更を行うための条件。
Appendix D ヒントと規約		Emacs Lispのコーディング規約にたいするアドバイス。
Appendix E GNU Emacsの内部		Emacsのビルドとダンプ、内部的な構造。
Appendix F 標準的なエラー		いくつかの標準的なエラーシンボルのリスト。
Appendix G 標準的なキーマップ		いくつかの標準的なキーマップのリスト。
Appendix H 標準的なフック		いくつかの標準的なフック変数のリスト。

Index		概念、関数、変数、その他用語のインデックス。

— 詳細ノードリスト — ——————————— 以下はすでにリストしたもののサブノードであるようなノードのリストです。1ステップで移動できるようにここに記します: Introduction
1.1 注意事項		不備な点と、助けを求める方法。
1.2 Lispの歴史		Emacs LispはMaclispの子孫です。
1.3 表記について		このマニュアルのフォーマット方法。
1.4 バージョンの情報		実行中のEmacsのバージョンは?
1.5 謝辞		このマニュアルの著者、編集者、スポンサー。
Conventions
1.3.1 用語について		このマニュアルで使用する用語の説明。
1.3.2 `nil`と`t`		シンボル`nil`と`t`の使用方法。
1.3.3 評価の表記		評価の例で使用するフォーマット。
1.3.4 プリントの表記		テキストのプリント例で使用するフォーマット。
1.3.5 エラーメッセージ		エラー例で使用するフォーマット。
1.3.6 バッファーテキストの表記		例のバッファー内容で使用するフォーマット。
1.3.7 説明のフォーマット		関数や変数などの説明にたいする表記。
Format of Descriptions
1.3.7.1 関数の説明例		架空の関数`foo`にたいする記述例。
1.3.7.2 変数の説明例		架空の変数`electric-future-map`にたいする記述例。
Lisp Data Types
2.1 プリント表現と読み取り構文		Lispオブジェクトがテキストとして表現される方法。
2.2 コメント		コメントとコメント書式の慣例。
2.3 プログラミングの型		すべてのLispシステムに存在する型。
2.4 編集用の型		Emacs固有の型。
2.5 循環オブジェクトの読み取り構文		循環構造にたいする入力構文。
2.6 型のための述語		型に関連するテスト。
2.7 同等性のための述語		2つのオブジェクトが等しいかのテスト。
Programming Types
2.3.1 整数型		小数部のない数字。
2.3.2 浮動小数点数型		広い範囲をもつ、小数部をもつ数字。
2.3.3 文字型		文字、数字、コントロール文字にたいする表現。
2.3.4 シンボル型		関数、変数、プロパティーリストを参照する、一意に識別される多目的オブジェクト。
2.3.5 シーケンス型		リストと配列はどちらもシーケンスに分類される。
2.3.6 コンスセルとリスト型		コンスセル、および(コンスセルにより作られる)リスト。
2.3.7 配列型		配列には文字列とベクターが含まれる。
2.3.8 文字列型		(効率的な)文字の配列。
2.3.9 ベクター型		1次元の配列。
2.3.10 文字テーブル型		文字によりインデックスされる1次元の疎な配列。
2.3.11 ブールベクター型		`t`と`nil`からなる、1次元の配列。
2.3.12 ハッシュテーブル型		とても高速な参照用のテーブル。
2.3.13 関数型		他の場所から呼び出せる実行可能なコードの断片。
2.3.14 マクロ型		より基本的だが少し見栄えの悪い、式を他の式に展開する手法。
2.3.15 プリミティブ関数型		Lispから呼び出せる、Cで記述された関数。
2.3.16 バイトコード関数型		Lispで記述されてからコンパイルされた関数。
2.3.17 Record Type		Compound objects with programmer-defined types.
2.3.18 Type Descriptors		Objects holding information about types.
2.3.19 autoload型		頻繁に使用されない関数を自動的にロードするために使用される型。
2.3.20 Finalizer Type		Runs code when no longer reachable.
Character Type
2.3.3.1 基本的な文字構文		標準的な文字の構文。
2.3.3.2 一般的なエスケープ構文		文字をコードにより指定する方法。
2.3.3.3 コントロール文字構文		コントロール文字の構文。
2.3.3.4 メタ文字構文		メタ文字の構文。
2.3.3.5 その他の文字修飾ビット		ハイパー、スーパー、アルト文字の構文。
Cons Cell and List Types
2.3.6.1 ボックスダイアグラムとしてのリストの描写		リストを絵で書いたら。
2.3.6.2 ドットペア表記		コンスセルの一般的な構文。
2.3.6.3 連想リスト型		コンスセルの一般的な構文。
String Type
2.3.8.1 文字列の構文		Lisp文字列を指定する方法。
2.3.8.2 文字列内の非ASCII文字		文字列内の国際化文字。
2.3.8.3 文字列内の非プリント文字		文字列内の印刷不可能なリテラル文字。
2.3.8.4 文字列内のテキストプロパティ		テキストプロパティーをともなう文字列。
Editing Types
2.4.1 バッファー型		編集のための基本オブジェクト。
2.4.2 マーカー型		バッファー内の位置。
2.4.3 ウィンドウ型		バッファーはウィンドウ内に表示する。
2.4.4 フレーム型		ウィンドウはフレームを細分化する。
2.4.5 端末型		フレームを表示する端末デバイス。
2.4.6 ウィンドウ構成型		フレームが細分化された方法を記録する。
2.4.7 フレーム構成型		すべてのフレームの状態を記録する。
2.4.8 プロセス型		背後のOS上で実行されるEmacsのサブプロセス。
2.4.9 Thread Type		A thread of Emacs Lisp execution.
2.4.10 Mutex Type		An exclusive lock for thread synchronization.
2.4.11 Condition Variable Type		Condition variable for thread synchronization.
2.4.12 ストリーム型		文字の受信と送信。
2.4.13 キーマップ型		キーストロークがどの関数を呼び出すか。
2.4.14 オーバーレイ型		オーバーレイが表示される方法。
2.4.15 フォント型		テキストを表示するフォント。
Numbers
3.1 整数の基礎		整数の表現と範囲。
3.2 浮動小数点数の基礎		浮動少数の表現と範囲。
3.3 数値のための述語		数にたいするテスト。
3.4 数値の比較		同一性と非同一性の述語。
3.5 数値の変換		浮動小数点数から整数、またはその逆の変換。
3.6 算術演算		加減乗除の方法。
3.7 丸め処理		浮動小数点数の明示的な丸め。
3.8 ビット演算 on Integers		論理的なand、or、not、shift。
3.9 標準的な数学関数		三角関数、指数、対数関数。
3.10 乱数		予測可能または不可能な乱数の取得。
Strings and Characters
4.1 文字列と文字の基礎		文字列と文字の基本的なプロパティー。
4.2 文字列のための述語		オブジェクトが文字列か文字かをテストする。
4.3 文字列の作成		新しい文字列を割り当てる関数。
4.4 文字列の変更		既存の文字列の内容を変更する。
4.5 文字および文字列の比較		文字または文字列を比較する。
4.6 文字および文字列の変換		文字から文字列、文字から文字列への変換。
4.7 文字列のフォーマット		`format`: `printf`’のEmacsバージョン。
4.8 Lispでの大文字小文字変換		case変換関数。
4.9 caseテーブル		case変換のカスタマイズ。
Lists
5.1 リストとコンスセル		コンスセルからリストが作られる方法。
5.2 リストのための述語		このオブジェクトはリストか? 2つのリストを比較する。
5.3 リスト要素へのアクセス		リストの一部を抽出する。
5.4 コンスセルおよびリストの構築		リスト構造の作成。
5.5 リスト変数の変更		変数に保存されたリストにたいする変更。
5.6 既存のリスト構造の変更		既存のリストに新しい要素を保存する。
5.7 集合としてのリストの使用		リストは有限な数学集合を表現できる。
5.8 連想リスト		リストは有限な関係またはマッピングを表現できます。
5.9 プロパティリスト		要素ペアのリスト。
Modifying Existing List Structure
5.6.1 `setcar`によるリスト要素の変更		リスト内の要素の置き換え。
5.6.2 リストのCDRの変更		リストの根幹部分の置き換え。これは要素の追加や削除に使用される。
5.6.3 リストを再配置する関数		リスト内の要素の再配置、リストの合成。
Property Lists
5.9.1 プロパティリストと連想リスト		プロパティーリストと連想リストの利点の比較。
5.9.2 プロパティリストと外部シンボル		他の場所に保管されたプロパティーリストへのアクセス。
Sequences, Arrays, and Vectors
6.1 シーケンス		任意の種類のシーケンスを許す関数。
6.2 配列		Emacs Lispの配列の特徴。
6.3 配列を操作する関数		Emacs Lispの配列の特徴。
6.4 ベクター		Emacs Lispベクターの特質。
6.5 ベクターのための関数		ベクターのための特別な関数。
6.6 文字テーブル		文字テーブルを扱う方法。
6.7 ブールベクター		ブールベクターを扱う方法。
6.8 オブジェクト用固定長リングの管理		オブジェクトの固定サイズのリングを管理する。
Records
7.1 Record Functions		Functions for records.
7.2 Backward Compatibility		Compatibility for cl-defstruct.
Hash Tables
8.1 ハッシュテーブルの作成		ハッシュテーブルを作成する関数。
8.2 ハッシュテーブルへのアクセス		ハッシュテーブルの内容の読み書き。
8.3 ハッシュの比較の定義		新たな比較方法の定義。
8.4 ハッシュテーブルのためのその他関数		その他。
Symbols
9.1 シンボルの構成要素		シンボルは名前、値、関数定義、プロパティーリストをもつ。
9.2 シンボルの定義		定義は、シンボルが使用される方法を示す。
9.3 シンボルの作成とintern		シンボルが一意に保たれる方法。
9.4 シンボルのプロパティ		さまざまな情報を記録するために、各シンボルはプロパティーリストをもつ。
Symbol Properties
9.4.1 シンボルのプロパティへのアクセス		シンボルプロパティーへのアクセス。
9.4.2 シンボルの標準的なプロパティ		シンボルプロパティーの標準的な意味。
Evaluation
10.1 評価の概要		事の在り方における評価。
10.2 フォームの種類		さまざまなオブジェクト類が評価される方法。
10.3 クォート		(プログラム内に定数を配すための)評価の回避。
10.4 バッククォート		リスト構造の、より簡単な構築。
10.5 eval		Lispインタープリターを明示的に呼び出す方法。
Kinds of Forms
10.2.1 自己評価を行うフォーム		自分自身を評価するフォーム。
10.2.2 シンボルのフォーム		変数として評価されるシンボル。
10.2.3 リストフォームの分類		さまざまな種類のリストフォームを区別する方法。
10.2.4 シンボル関数インダイレクション		シンボルがリストのcarにある場合、そのシンボルを通じて実際の関数を見つける。
10.2.5 関数フォームの評価		関数を呼び出すフォーム。
10.2.6 Lispマクロの評価		マクロを呼び出すフォーム。
10.2.7 スペシャルフォーム		Special forms are idiosyncratic primitives, most of them extremely important.
10.2.8 自動ロード		実際の定義を含むファイルのロードをセットアップする関数。
Control Structures
11.1 順序		テキスト順の評価。
11.2 条件		`if`、`cond`、`when`、`unless`。
11.3 条件の組み合わせ		`and`、`or`、`not`。
11.4 繰り返し		`while`ループ。
11.5 Generators		Generic sequences and coroutines.
11.6 非ローカル脱出		シーケンスの外へジャンプ。
Conditionals
11.2.1 パターンマッチングによるcase文		How to use `pcase`.
Nonlocal Exits
11.6.1 明示的な非ローカル脱出: `catch`と`throw`		プログラム自身の目的による非ローカル脱出。
11.6.2 `catch`と`thrown`の例		このような非ローカル脱出が記述される方法。
11.6.3 エラー		エラーがシグナル・処理される方法。
11.6.4 非ローカル脱出のクリーンアップ		エラーが発生した場合のクリーンアップフォーム実行のアレンジ。
Errors
11.6.3.1 エラーをシグナルする方法		エラーを報告する方法。
11.6.3.2 Emacsがエラーを処理する方法		エラーを報告するときEmacsが何を行なうか。
11.6.3.3 エラーを処理するコードの記述		エラーをトラップして実行を継続する方法。
11.6.3.4 エラーシンボルとエラー条件		エラートラッピングのために、エラーをクラス分けする方法。
Variables
12.1 グローバル変数		どの場所でも永続的に存在する変数の値。
12.2 変更不可な変数		Variables that never change.
12.3 ローカル変数		一時的にのみ存在する存在する変数の値。
12.4 When a Variable is Void		値を持たないシンボル。
12.5 グローバル変数の定義		シンボルが変数として使用されていることを宣言する定義。
12.6 堅牢な変数定義のためのヒント		変数を定義するときに考慮すべき事項。
12.7 変数の値へのアクセス		実行時に判明する名前をもつ変数の値を確認する。
12.8 変数の値のセット		変数に新しい値を格納する。
12.9 Running a function when a variable is changed.
12.10 変数のバインディングのスコーピングルール		Lispがローカル値とグローバル値を選択する方法。
12.11 バッファーローカル変数		1つのバッファーないだけで効果をもつ変数の値。
12.12 ファイルローカル変数		ファイル内にリストされたローカル変数の処理。
12.13 ディレクトリーローカル変数		ディレクトリー内のすべてのファイルで共通のローカル変数。
12.14 Connection Local Variables		Local variables common for remote connections.
12.15 変数のエイリアス		他の変数のエイリアスとなる変数。
12.16 値を制限された変数		任意のLispオブジェクトを値とすることができない、定数ではない変数。
12.17 ジェネリック変数		変数の概念の拡張。
Scoping Rules for Variable Bindings
12.10.1 ダイナミックバインディング		Emacs内でのローカル変数にたいするデフォルトのバインディング。
12.10.2 ダイナミックバインディングの正しい使用		ダイナミックバインディングによる問題を回避する。
12.10.3 レキシカルバインディング		ローカル変数にたいする他の種類のバインディング。
12.10.4 レキシカルバインディングの使用		レキシカルバインディングを有効にする方法。
Buffer-Local Variables
12.11.1 バッファーローカル変数の概要		イントロダクションと概念。
12.11.2 バッファーローカルなバインディングの作成と削除
12.11.3 バッファーローカル変数のデフォルト値		自身ではバッファーローカルな値をもたないバッファーで参照されるデフォルト値。
Generalized Variables
12.17.1 `setf`マクロ
12.17.2 新たな`setf`フォーム		新たな`setf`フォームの定義。
Functions
13.1 関数とは?		Lisp関数 vs. プリミティブ。専門用語。
13.2 ラムダ式		関数がLispオブジェクトとして表現される方法。
13.3 関数の命名		シンボルは関数を名づける役割を果たすことができる。
13.4 関数の定義		関数定義のためのLisp式。
13.5 関数の呼び出し		既存の関数を使う方法。
13.6 関数のマッピング		リストの各要素などに関数を適用する。
13.7 無名関数		ラムダ式、それは無名の関数。
13.8 Generic Functions		Polymorphism, Emacs-style.
13.9 関数セルの内容へのアクセス		シンボルの関数定義へのアクセスとセット。
13.10 クロージャー		レキシカル環境に囲まれた関数。
13.11 Emacs Lisp関数にたいするアドバイス		Adding to the definition of a function.
13.12 関数を陳腐と宣言する
13.13 インライン関数Inline Functions		コンパイラーによりインライン展開される関数。
13.14 `declare`フォーム		関数についての補足的な情報の追加。
13.15 コンパイラーへの定義済み関数の指示		関数が定義されていることをコンパイラーに知らせる。
13.16 安全に関数を呼び出せるかどうかの判断		呼び出しても安全な関数なのか判断する。
13.17 関数に関するその他トピック		関数が動作する方法において特別な意味をもつ、特定のLispプリミティブのクロスリファレンス。
Lambda Expressions
13.2.1 ラムダ式の構成要素		ラムダ式のパーツ。
13.2.2 単純なラムダ式の例		シンプルな例。
13.2.3 引数リストのその他機能		引数リストの詳細と特別な機能。
13.2.4 関数のドキュメント文字列		関数内にドキュメントを記述する方法。
Advising Emacs Lisp Functions
13.11.1 アドバイスを操作するためのプリミティブ		Primitives to manipulate advice.
13.11.2 名前つき関数にたいするアドバイス		Advising named functions.
13.11.3 Ways to compose advice
13.11.4 古いdefadviceを使用するコードの改良		Adapting code using the old defadvice.
Macros
14.1 単純なマクロの例		基本的な例。
14.2 マクロ呼び出しの展開		いつ、なぜ、どのようにしてマクロが展開されるか。
14.3 マクロとバイトコンパイル		コンパイラーによりマクロが展開される方法。
14.4 マクロの定義		マクロ定義を記述する方法。
14.5 マクロ使用に関する一般的な問題		マクロ引数を何回も評価しないこと。ユーザーの変数を隠さないこと。
14.6 マクロのインデント		マクロ呼び出しのインデント方法の指定。
Common Problems Using Macros
14.5.1 タイミング間違い		マクロ内ではなく展開形で作業を行う。
14.5.2 マクロ引数の多重評価		展開形は各マクロ引数を一度評価すること。
14.5.3 マクロ展開でのローカル変数		展開形でのローカル変数バインディングには特に注意を要する。
14.5.4 展開におけるマクロ引数の評価		評価せずに展開形の中に配置すること。
14.5.5 マクロが展開される回数は?		展開が行われる回数への依存を避ける。
Customization Settings
15.1 一般的なキーワードアイテム		すべての種類のカスタマイズ宣言に共通なキーワード引数。
15.2 カスタマイズグループの定義		カスタマイズグループ定義の記述。
15.3 カスタマイズ変数の定義		ユーザーオプションの宣言。
15.4 カスタマイズ型		ユーザーオプションの型指定。
15.5 カスタマイズの適用		カスタマイズセッティングを適用する関数。
15.6 カスタムテーマ		カスタムテーマの記述。
Customization Types
15.4.1 単純型		シンプルなカスタマイズ型(sexp、integerなど)。
15.4.2 複合型		他の型やデータから新しい型を構築する。
15.4.3 リストへのスプライス		`:inline`で要素をリストに結合する。
15.4.4 型キーワード		カスタマイズ型でのキーワード／引数ペアー
15.4.5 新たな型の定義		型に名前をつける。
Loading
16.1 プログラムがロードを行う方法		`load`’関数、その他。
16.2 ロードでの拡張子		`load`’が試みられるサフィックスについての詳細。
16.3 ライブラリー検索		ロードするライブラリーの検索。
16.4 非ASCII文字のロード		Emacs Lispファイル内の非ASCII文字。
16.5 autoload		オートロードのための関数のセットアップ。
16.6 多重ロード		ファイルを2度ロードする場合の配慮。
16.7 名前つき機能		まだロードされていないライブラリーのロード。
16.8 どのファイルで特定のシンボルが定義されているか		特定のシンボルがどのファイルで定義されているかの検索。
16.9 アンロード		How to unload a library that was loaded.
16.10 ロードのためのフック		特定のライブラリーがロードされたとき実行されるコードの提供。
16.11 Emacs Dynamic Modules		Modules provide additional Lisp primitives.
Byte Compilation
17.1 バイトコンパイル済みコードのパフォーマンス		バイトコンパイルによるスピードアップ例。
17.2 バイトコンパイル関数
17.3 ドキュメント文字列とコンパイル		ドキュメント文字列のダイナミックロード。
17.4 個別関数のダイナミックロード		個々の関数のダイナミックロード。
17.5 コンパイル中の評価		コンパイル時に評価されるコード。
17.6 コンパイラーのエラー		コンパイラーのエラーメッセージの扱い。
17.7 バイトコード関数オブジェクト		バイトコンパイル済み関数に使用されるデータ型。
17.8 逆アセンブルされたバイトコード		バイトコードの逆アセンブル。バイトコードの読み方。
Debugging Lisp Programs
18.1 Lispデバッガ		Emacs Lisp評価機能にたいするデバッガ。
18.2 Edebug		Emacs Lispソースレベルデバッガ。
18.3 無効なLisp構文のデバッグ		シンタックスエラーを見つける方法。
18.4 カバレッジテスト		プログラムのすべての分岐を確実にテストする。
18.5 プロファイリング		あなたのコードが使用するリソースの計測。
The Lisp Debugger
18.1.1 エラーによるデバッガへのエンター		エラー発生時にデバッガにエンターする。
18.1.2 無限ループのデバッグ		exitしないプログラムの停止デバッグ。
18.1.3 関数呼び出しによるデバッガへのエンター		特定の関数が呼び出されたときにデバッガにエンターする。
18.1.4 Entering the debugger when a variable is modified		Entering it when a variable is modified.
18.1.5 明示的なデバッガへのエントリー		プログラム内の特定箇所でデバッガにエンターする。
18.1.6 デバッガの使用		デバッガが行なうこと: そこで何を目にするか。
18.1.7 デバッガのコマンド		デバッガで使用するコマンド。
18.1.8 デバッガの呼び出し		関数`debug`の呼び出し方。
18.1.9 デバッガの内部		デバッガのサブルーチン、およびグローバル変数。
Edebug
18.2.1 Edebugの使用		Edebug使用のための手引き。
18.2.2 Edebugのためのインストルメント		Edebugでデバッグするために、コードをインストルメント(計装)しなければならないe
18.2.3 Edebugの実行モード		多かれ少なかれ、ストップする実行モード。
18.2.4 ジャンプ		特定の位置にジャンプするコマンド。
18.2.5 その他のEdebugコマンド		さまざまなコマンド。
18.2.6 ブレーク		プログラムをストップさせるbreakpointのセット。
18.2.7 エラーのトラップ		Edebugでのエラーのトラップ。
18.2.8 Edebugのビュー		Edebugの内側と外側のビュー。
18.2.9 評価		Edebugでの式の評価。
18.2.10 評価 List Buffer		Edebugにエンターするたびに値が表示される式。
18.2.11 Edebugでのプリント		プリントのカスタマイズ。
18.2.12 トレースバッファー		バッファー内で採れを生成する方法。
18.2.13 カバレッジテスト		評価をカバレッジテストする方法。
18.2.14 コンテキスト外部		Edebugが保存およびリストアするデータ。
18.2.15 Edebugとマクロ		マクロ呼び出しをハンドルする方法の指定。
18.2.16 Edebugのオプション		Edebugをカスタマイズするオプション変数。
Breaks
18.2.6.1 Edebugのブレークポイント		ストップポイントのbreakpoint。
18.2.6.2 グローバルなブレーク条件		イベントによるbreak。
18.2.6.3 ソースブレークポイント		ソースコードに埋め込まれたbreakpoint。
The Outside Context
18.2.14.1 停止するかどうかのチェック		何を行うかをEdebugが決定するタイミング。
18.2.14.2 Edebugの表示の更新		Edebugがディスプレイを更新するタイミング。
18.2.14.3 Edebugの再帰編集		Edebugが実行をストップするタイミング。
Edebug and Macros
18.2.15.1 マクロ呼び出しのインストルメント		基本的な問題点。
18.2.15.2 仕様リスト		式の複雑なパターンを指定する方法。
18.2.15.3 仕様でのバックトレース		マッチに失敗したときEdebugが行なうこと。
18.2.15.4 仕様の例		Edebug仕様を理解するために。
Debugging Invalid Lisp Syntax
18.3.1 過剰な開カッコ		誤った開カッコと閉カッコを探す方法。
18.3.2 過剰な閉カッコ		誤った閉カッコと開カッコを探す方法。
Reading and Printing Lisp Objects
19.1 読み取りとプリントの概念		ストリーム、読み取り、プリントの概観。
19.2 入力ストリーム		入力ストリームとして使用できる、さまざまなデータ型。
19.3 入力関数		テキストからLispオブジェクトを読み取る関数。
19.4 出力ストリーム		出力ストリームとして使用できる、さまざまなデータ型。
19.5 出力関数		テキストとしてLispオブジェクトをプリントする関数。
19.6 出力に影響する変数		プリント関数が何を行うか制御する変数。
Minibuffers
20.1 ミニバッファーの概念		ミニバッファーに関する基本的な情報。
20.2 ミニバッファーでのテキスト文字列の読み取り		そのままのテキスト文字列を読み取る方法。
20.3 ミニバッファーでのLispオブジェクトの読み取り		Lispオブジェクトや式を読み取る方法。
20.4 ミニバッファーのヒストリー		ユーザーが再利用できるように以前のミニバッファー入力は記録される。
20.5 入力の初期値		ミニバッファーにたいして初期内容を指定する。
20.6 補完		補完の呼び出しとカスタマイズ方法。
20.7 Yes-or-Noによる問い合わせ		問いにたいし単純な答えを求める。
20.8 複数のY-or-Nの問い合わせ		一連の似たような問いに答える。
20.9 パスワードの読み取り		端末からパスワードを読み取る。
20.10 ミニバッファーのコマンド		ミニバッファー内でキーバインドとして使用されるコマンド。
20.11 ミニバッファーのウィンドウ		特殊なミニバッファーウィンドウを処理する。
20.12 ミニバッファーのコンテンツ		どのようなコマンドがミニバッファーのテキストにアクセスするか。
20.13 再帰的なミニバッファー		ミニバッファーへの再帰的なエントリーが許容されるかどうか。
20.14 ミニバッファー、その他の事項		カスタマイズ用のさまざまなフックや変数。
Completion
20.6.1 基本的な補完関数		文字列を補完する低レベル関数。
20.6.2 補完とミニバッファー		補完つきでミニバッファーを呼び出す。
20.6.3 補完を行うミニバッファーコマンド
20.6.4 高レベルの補完関数		特別なケースに有用な補完(バッファー名や変数名などの読み取り)。
20.6.5 ファイル名の読み取り		ファイル名やシェルコマンドの読み取りに補完を使用する。
20.6.6 補完変数		補完の挙動を制御する変数。
20.6.7 プログラムされた補完		独自の補完関数を記述する。
20.6.8 通常バッファーでの補完		通常バッファー内でのテキスト補完。
Command Loop
21.1 コマンドループの概要		コマンドループがコマンドを読み取る方法。
21.2 コマンドの定義		関数が引数を読み取る方法を指定する。
21.3 interactiveな呼び出し		引数を読み取るようにコマンドを呼び出す。
21.4 interactiveな呼び出しの区別		インタラクティブな呼び出しとコマンドを区別する。
21.5 コマンドループからの情報		検証用にコマンドループによりセットされる変数。
21.6 コマンド後のポイントの調整		コマンドの後にポイント位置を調整する。
21.7 入力イベント		入力を読み取るとき、入力がどのように見えるか。
21.8 入力の読み取り		キーボードやマウスからの入力イベントを読み取る方法。
21.9 スペシャルイベント		即座かつ個別に処理されるイベント。
21.10 時間の経過や入力の待機		ユーザー入力または経過時間の待機。
21.11 quit		`C-g`’が機能する方法。quitをcatchまたは延期する方法。
21.12 プレフィクスコマンド引数		コマンドがプレフィクス引数が機能するようにセットするための方法。
21.13 再帰編集		再帰編集へのエンター、なぜ通常は再帰編集を行うべきでないのか。
21.14 コマンドの無効化		コマンドループが無効なコマンドを扱う方法。
21.15 コマンドのヒストリー		コマンドヒストリーがセットアップされる方法と、どのようにアクセスされるか。
21.16 キーボードマクロ		キーボードマクロが実装される方法。
Defining Commands
21.2.1 `interactive`の使用		`interactive`’にたいする一般的なルール。
21.2.2 `interactive`にたいするコード文字		さまざまな方法で引数を読み取る標準的な文字のコード。
21.2.3 `interactive`の使用例		インタラクティブ引数を読み取る方法の例。
21.2.4 コマンド候補からの選択
Input Events
21.7.1 キーボードイベント		Ordinary characters – keys with symbols on them.
21.7.2 ファンクションキー		Function keys – keys with names, not symbols.
21.7.3 マウスイベント		マウスイベントの概観。
21.7.4 クリックイベント		マウスボタンのプッシュとリリース。
21.7.5 ドラッグイベント		ボタンをリリースする前のマウス移動。
21.7.6 ボタンダウンイベント		ボタンがプッシュされて、まだリリースされていない状態。
21.7.7 リピートイベント		ダブル、トリプルのクリック(またはドラッグ、ダウン)
21.7.8 モーションイベント		ボタンを押さずに、マウスだけを移動する。
21.7.9 フォーカスイベント		フレーム間のマウス移動。
21.7.10 その他のシステムイベント		システムが生成可能なその他のイベント。
21.7.11 イベントの例		マウスイベントの例。
21.7.12 イベントの分類		イベントシンボル内の修飾キーを見つける。イベント型。
21.7.13 マウスイベントへのアクセス		マウスイベントから情報抽出する関数。
21.7.14 スクロールバーイベントへのアクセス		スクロールバーイベントから情報取得する関数。
21.7.15 文字列内へのキーボードイベントの配置		文字列内にキーボード文字イベントを配すための特別な配慮。
Reading Input
21.8.1 キーシーケンス入力		キーシーケンスを読み取る方法。
21.8.2 単一イベントの読み取り		イベントを1つだけ読み取る方法。
21.8.3 入力イベントの変更と変換		Emacsが読み取られたイベントを変更する方法。
21.8.4 入力メソッドの呼び出し		入力メソッドを使用するイベントを読み取る方法。
21.8.5 クォートされた文字の入力		文字の指定をユーザーに問い合わせる。
21.8.6 その他のイベント入力の機能		入力イベントの最読み取りや破棄の方法。
Keymaps
22.1 キーシーケンス		Lispオブジェクトとしてのキーシーケンス。
22.2 キーマップの基礎		キーマップの基本概念。
22.3 キーマップのフォーマット		キーマップはLispオブジェクトとしてどのように見えるか。
22.4 キーマップの作成		キーマップを作成、コピーする関数。
22.5 継承とキーマップ		キーマップが他のキーマップのバインディングを継承する方法。
22.6 プレフィクスキー		キーマップの定義としてキーを定義する。
22.7 アクティブなキーマップ		Emacsがアクティブなキーマップでキーバインディングを探す方法。
22.8 アクティブなキーマップの検索		アクティブなマップ検索のLisp処理概要。
22.9 アクティブなキーマップの制御		各バッファーは標準(グローバル)のバインディングをオーバーライドするためのキーマップをもつ。マイナーモードもそれらをオーバーライドできる。
22.10 キーの照合		1つのキーマップから、あるキーのバインディングを探す。
22.11 キー照合のための関数		キールックアップを要求する方法。
22.12 キーバインディングの変更		キーマップ内でのキーの再定義。
22.13 コマンドのリマップ		キーマップはあるコマンドを他のコマンドに変換できる。
22.14 イベントシーケンス変換のためのキーマップ		イベントシーケンスを変換するキーマップ。
22.15 キーのバインドのためのコマンド		キーの再定義にたいするインタラクティブなインターフェイス。
22.16 キーマップのスキャン		ヘルプをプリントするためにすべてのキーマップを走査する。
22.17 メニューキーアップ		キーマップとしてキーマップを定義する。
Menu Keymaps
22.17.1 メニューの定義		メニューを定義するキーマップを作成する方法。
22.17.2 メニューとマウス		ユーザーがマウスでメニューを操作する方法。
22.17.3 メニューとキーボード		ユーザーがキーボードでメニューを操作する方法。
22.17.4 メニューの例		シンプルなメニューの作成。
22.17.5 メニューバー Bar		メニューバーのカスタマイズ方法。
22.17.6 ツールバー		イメージ行のツールバー。
22.17.7 メニューの変更		メニューへ新たなアイテムを追加する方法。
22.17.8 easy-menu		メニュー作成のための便利なマクロ。
Defining Menus
22.17.1.1 単純なメニューアイテム		単純なメニューのキーバインディング。
22.17.1.2 拡張メニューアイテム		複雑なメニューアイテムの定義。
22.17.1.3 メニューセパレーター		メニューに水平ラインを描画する。
22.17.1.4 メニューアイテムのエイリアス		メニューアイテムにコマンドエイリアスを使用する。
Major and Minor Modes
23.1 フック		フックの使い方と、フックを提供するコードの記述方法。
23.2 メジャーモード		メジャーモードの定義。
23.3 マイナーモード		マイナーモードの定義。
23.4 モードラインのフォーマット		モードラインに表示されるテキストのカスタマイズ。
23.5 Imenu		バッファーで作成された定義のメニューを提供する。
23.6 Font Lockモード		モードが構文に応じてテキストをハイライトする方法。
23.7 コードの自動インデント		メジャーモードにたいするインデントをEmacsに伝える方法。
23.8 Desktop Saveモード		Emacsセッション間でモードがバッファー状態を保存する方法。
Hooks
23.1.1 フックの実行		フックの実行方法。
23.1.2 フックのセットSetting Hooks		関数をフックに登録、削除する方法。
Major Modes
23.2.1 メジャーモードの慣習		キーマップなどにたいするコーディング規約。
23.2.2 Emacsがメジャーモードを選択する方法		Emacsが自動的にメジャーモードを選択する方法。
23.2.3 メジャーモードでのヘルプ入手		モードの使用方法の探し方。
23.2.4 派生モードの定義		他のメジャーモードにもとづき新たなメジャーモードを定義する。
23.2.5 基本的なメジャーモード		他のモードからよく派生元とされるモード。
23.2.6 モードフック		メジャーモード関数の最後に実行されるフック。
23.2.7 Tabulated Listモード		表形式データを含むバッファーにたいする親モード。
23.2.8 ジェネリックモード		コメント構文とFont
23.2.9 メジャーモードの例		TextモードとLispモード。
Minor Modes
23.3.1 マイナーモード記述の規約		マイナーモードを記述するためのTips。
23.3.2 キーマップとマイナーモード		マイナーモードが自身のキーマップをもつための方法。
23.3.3 マイナーモードの定義		マイナーモードを定義するための便利な機能。
Mode Line Format
23.4.1 モードラインの基礎		モードライン制御の基本概念。
23.4.2 モードラインのデータ構造		モードラインを制御するデータ構造。
23.4.3 モードライン制御のトップレベル		トップレベル変数、mode-line-format。
23.4.4 モードラインで使用される変数		そのデータ構造で使用される変数。
23.4.5 モードラインでの`%`構造		モードラインへの情報の配置。
23.4.6 モードラインでのプロパティ		モードライン内でのテキストプロパティの使用。
23.4.7 ウィンドウのヘッダーライン		モードラインに類似した最上部のライン。
23.4.8 モードラインのフォーマットのエミュレート		モードラインのようにテキストをフォーマットする。
Font Lock Mode
23.6.1 Font Lockの基礎		Font Lockカスタマイズの概要。
23.6.2 検索ベースのフォント化		正規表現にもとづくフォント表示。
23.6.3 検索ベースのフォント化のカスタマイズ		検索ベースフォント表示のカスタマイズ。
23.6.4 Font Lockのその他の変数		追加のカスタマイズ機能。
23.6.5 Font Lockのレベル		多なりとも少ユーザーが選択できるように、それぞれのモードは代替レベルを定義できる。
23.6.6 事前計算されたフォント化		バッファーコンテンツを生成するLispプログラムが、どのようにしてそれをフォント表示する方法も指定できるか。
23.6.7 Font Lockのためのフェイス		Font Lockにたいする具体的な特殊フェイス。
23.6.8 構文的なFont Lock		構文テーブルにもとづくフォント表示。
23.6.9 複数行のFont Lock構造		Font Lockに複数行構成の正しいハイライトを強制する方法。
Multiline Font Lock Constructs
23.6.9.1 複数行のFont Lock		テキストプロパティで複数行塊をマークする。
23.6.9.2 バッファー変更後のリージョンのフォント化		バッファー変更後にどのリージョンを再フォント表示するかを制御する。
Automatic Indentation of code
23.7.1 SMIE: 無邪気なインデントエンジン		SMIE: Simple Minded Indentation Engine(純真なインデントエンジン)。
Simple Minded Indentation Engine
23.7.1.1 SMIEのセットアップと機能
23.7.1.2 演算子順位文法		非常にシンプルなパース技術。
23.7.1.3 言語の文法の定義		言語の文法を定義する。
23.7.1.4 トークンの定義
23.7.1.5 非力なパーサーの使用		パーサー制限の回避策。
23.7.1.6 インデントルールの指定
23.7.1.7 インデントルールにたいするヘルパー関数
23.7.1.8 インデントルールの例
23.7.1.9 インデントのカスタマイズ
Documentation
24.1 ドキュメントの基礎		ドキュメント文字列が定義、格納される場所。
24.2 ドキュメント文字列へのアクセス		Lispプログラムがドキュメント文字列にアクセスする方法。
24.3 ドキュメント内でのキーバインディングの置き換え		カレントキーバインディングの置き換え。
24.4 Text Quoting Style		Quotation marks in doc strings and messages.
24.5 ヘルプメッセージの文字記述		非プリント文字やキーシーケンスをプリント可能な記述にする。
24.6 ヘルプ関数		Emacsヘルプ機能により使用されるサブルーチン。
Files
25.1 ファイルのvisit		編集のためにEmacsバッファーにファイルを読み込む。
25.2 バッファーの保存		変更されたバッファーをファイルに書き戻す。
25.3 ファイルの読み込み		ファイルをvisitせずにバッファーに読み込む。
25.4 ファイルの書き込み		バッファーの一部から新たなファイルに書き込む。
25.5 ファイルのロック		複数名による同時編集を防ぐためにファイルをlockまたはunlockする。
25.6 ファイルの情報		ファイルの存在、アクセス権、サイズのテスト。
25.7 ファイルの名前と属性の変更		ファイル名のリネームやパーミッションの変更など。
25.9 ファイルの名前		ファイル名の分解と展開。
25.10 ディレクトリーのコンテンツ		ディレクトリーないのファイルリストの取得。
25.11 ディレクトリーの作成・コピー・削除		ディレクトリーの作成と削除。
25.12 特定のファイル名の“Magic”の作成		特定のファイル名にたいする特別な処理。
25.13 ファイルのフォーマット変換		さまざまなファイルフォーマットへ/からの変換。
Visiting Files
25.1.1 ファイルをvisitする関数		visit用の通常のインターフェイス関数。
25.1.2 visitのためのサブルーチン		通常のvisit関数が使用する低レベルのサブルーチン。
Information about Files
25.6.1 アクセシビリティのテスト		そのファイルは読み取り可能か？書き込み可能か？
25.6.2 ファイル種別の区別		それはディレクトリー？それともシンボリックリンク？
25.6.3 本当の名前		シンボリックリンクが行き着くファイル名。
25.6.4 ファイルの属性		ファイルのサイズ？更新日時など。
25.6.5 拡張されたファイル属性		アクセス制御にたいするファイル属性の拡張。
25.6.6 標準的な場所へのファイルの配置		標準的な場所でファイルを見つける方法。
File Names
25.9.1 ファイル名の構成要素		ファイル名のディレクトリー部分と、それ以外。
25.9.2 絶対ファイル名と相対ファイル名		カレントディレクトリーにたいして相対的なファイル名。
25.9.3 ディレクトリーの名前		ディレクトリーとしてのディレクトリー名と、ファイルとしてのファイル名の違い。
25.9.4 ファイル名を展開する関数		相対ファイル名から絶対ファイル名への変換。
25.9.5 一意なファイル名の生成		一時ファイル用の名前の生成。
25.9.6 ファイル名の補完		与えられたファイル名にたいする補完を探す。
25.9.7 標準的なファイル名		パッケージが固定されたファイル名を使用する際に、種々のオペレーティングシステムをシンプルに処理する方法。
File Format Conversion
25.13.1 概要		`insert-file-contents`と`write-region`。
25.13.2 ラウンドトリップ仕様		`format-alist`の使用。
25.13.3 漸次仕様		非ペアー変換の指定。
Backups and Auto-Saving
26.1 ファイルのバックアップ		バックアップファイルの作成と名前選択の方法。
26.2 自動保存		auto-saveファイルの作成と名前選択の方法。
26.3 リバート		`revert-buffer`とその動作のカスタマイズ方法。
Backup Files
26.1.1 バックアップファイルの作成		Emacsがバックアップファイルを作成する方法とタイミング。
26.1.2 リネームかコピーのどちらでバックアップするか?		2つの選択肢: 古いファイルのリネームとコピー。
26.1.3 番号つきバックアップファイルの作成と削除		ソースファイルごとに複数のバックアップを保持する。
26.1.4 バックアップファイルの命名		バックアップファイル名の計算方法とカスタマイズ。
Buffers
27.1 バッファーの基礎		バッファーとは?
27.2 カレントバッファー		バッファーをカレントに指定することにより、プリミティブはバッファーのコンテンツにアクセスする。
27.3 バッファーの名前		バッファー名にたいするアクセスと変更。
27.4 バッファーのファイル名		バッファーファイル名は、どのファイルをvisitしているかを示す。
27.5 バッファーの変更		保存が必要なら、バッファーは“変更されている(modified)”。
27.6 バッファーの変更 Time		Determining whether the visited file was changed behind Emacs’s back.
27.7 読み取り専用のバッファー		読み取り専用バッファーでのテキスト変更は許されない。
27.8 バッファーリスト		すべての既存バッファーを閲覧する方法。
27.9 バッファーの作成		バッファーを作成する関数。
27.10 バッファーのkill		明示的にkillされるまで、バッファーは存在する。
27.11 インダイレクトバッファー		インダイレクトバッファーは、他のバッファーとテキストを共有する。
27.12 2つのバッファー間でのテキストの交換
27.13 バッファーのギャップ		バッファー内のギャップ。
Windows
28.1 Emacsウィンドウの基本概念		ウィンドウ使用についての基本情報。
28.2 ウィンドウとフレーム		ウィンドウとそれらが表示されるフレームとの関連。
28.3 ウィンドウのサイズ		ウィンドウのサイズへのアクセス。
28.4 ウィンドウのリサイズ		ウィンドウのサイズの変更。
28.5 Preserving Window Sizes		Preserving the size of windows.
28.6 ウィンドウの分割		新たなウィンドウの作成。
28.7 ウィンドウの削除		フレームからのウィンドウの削除。
28.8 ウィンドウの再結合		ウィンドウの分割や削除時のフレームレイアウトの保存。
28.9 ウィンドウの選択		選択されたウィンドウとは、編集を行っているウィンドウである。
28.10 ウィンドウのサイクル順		既存のウィンドウ間の移動。
28.11 バッファーとウィンドウ		それぞれのウィンドウは、バッファーのコンテンツを表示する。
28.12 ウィンドウ内のバッファーへの切り替え		バッファー切り替えのための、より高レベルな関数。
28.13 表示するウィンドウの選択		バッファーを表示するウィンドウの選択方法。
28.14 `display-buffer`にたいするアクション関数		`display-buffer`用のサブルーチン。
28.15 バッファー表示の追加オプション		バッファー表示方法に影響する拡張オプション。
28.16 ウィンドウのヒストリー		それぞれのウィンドウは、表示されていたバッファーを記憶する。
28.17 専用のウィンドウ		特定のウィンドウ内で他のバッファーの表示を無効にする。
28.18 ウィンドウのquit		以前に表示していたバッファーの状態をリストアする方法。
28.19 Side Windows		Special windows on a frame’s sides.
28.20 Atomic Windows		Preserving parts of the window layout.
28.21 ウィンドウとポイント		それぞれのウィンドウは、自身の位置とポイントをもつ。
28.22 ウィンドウの開始位置と終了位置		ウィンドウ内でスクリーン表示されるテキストを表すバッファー位置。
28.23 テキスト的なスクロール		ウィンドウを通じたテキストの上下移動。
28.24 割り合いによる垂直スクロール		ウィンドウ上のコンテンツの上下移動。
28.25 水平スクロール		ウィンドウ上のコンテンツの横移動。
28.26 座標とウィンドウ		座標からウィンドウへの変換。
28.27 Mouse Window Auto-selection		Automatically selecting windows with the mouse.
28.28 ウィンドウの構成		スクリーンの情報の保存とリストア。
28.29 ウィンドウのパラメーター		ウィンドウへの追加情報の割り当て。
28.30 ウィンドウのスクロールと変更のためのフック		スクロール、ウィンドウのサイズ変更、ある特定のしきい値を超えたときに行われる再表示、ウィンドウ設定の変更にたいするフック。
Side Windows
28.19.1 Displaying Buffers in Side Windows		An action function for displaying buffers in side windows.
28.19.2 Side Window Options and Functions		Further tuning of side windows.
28.19.3 Frame Layouts with Side Windows		Setting up frame layouts with side windows.
Frames
29.1 フレームの作成		追加のフレームの作成。
29.2 複数の端末		異なる複数デバイス上での表示。
29.3 Frame Geometry		Geometric properties of frames.
29.4 フレームのパラメーター		フレームのサイズ、位置、フォント等の制御。
29.5 端末のパラメーター		端末上のすべてのフレームにたいして一般的なパラメーター。
29.6 フレームのタイトル		フレームタイトルの自動的な更新。
29.7 フレームの削除		明示的に削除されるまでフレームは存続する。
29.8 すべてのフレームを探す		すべての既存フレームを調べる方法。
29.9 ミニバッファーとフレーム		フレームが使用するミニバッファーを見つける方法。
29.10 入力のフォーカス		選択されたフレームの指定。
29.11 フレームの可視性		フレームは可視、不可視、またはアイコン化されているかもしれない。
29.12 Raising, Lowering and Restacking Frames
29.13 フレーム構成		すべてのフレームの状態の保存。
29.14 Child Frames		Making a frame the child of another.
29.15 マウスの追跡		マウス移動時のイベントの取得。
29.16 マウスの位置		マウスの場所や移動を問い合わせる。
29.17 ポップアップメニュー		ユーザーに選択させるためのメニューの表示。
29.18 ダイアログボックス		yes/noを問い合わせるためのボックスの表示。
29.19 ポインターの形状		マウスポインターのシェイプの指定。
29.20 ウィンドウシステムによる選択		他のXクライアントとのテキストの転送。
29.21 ドラッグアンドドロップ		ドラッグアンドドロップの実装の内部。
29.22 カラー名		カラー名定義の取得。
29.23 テキスト端末のカラー		テキスト端末のカラーの定義。
29.24 Xリソース		サーバーからのリソース値の取得。
29.25 ディスプレー機能のテスト		端末の機能の判定。
Frame Geometry
29.3.1 Frame Layout		Basic layout of frames.
29.3.2 Frame Font		The default font of a frame and how to set it.
29.3.3 Frame Position		The position of a frame on its display.
29.3.4 Frame Size		Specifying and retrieving a frame’s size.
29.3.5 Implied Frame Resizing		Implied resizing of frames and how to prevent it.
Frame Parameters
29.4.1 フレームパラメーターへのアクセス		フレームのパラメーターの変更方法。
29.4.2 フレームの初期パラメーター		フレーム作成時に指定するフレームパラメーター。
29.4.3 ウィンドウフレームパラメーター		ウィンドウシステムにたいするフレームパラメーターのリスト。
29.4.4 ジオメトリー		ジオメトリー仕様の解析。
Window Frame Parameters
29.4.3.1 基本パラメーター		基本的なパラメーター。
29.4.3.2 位置のパラメーター		スクリーン上のフレームの位置。
29.4.3.3 サイズのパラメーター		フレームのサイズ。
29.4.3.4 レイアウトのパラメーター		フレームのパーツのサイズと、一部パーツの有効化と無効化。
29.4.3.5 バッファーのパラメーター		表示済みまたは表示されるべきバッファーはどれか。
29.4.3.6 Frame Interaction Parameters		Parameters for interacting with other frames.
29.4.3.7 Mouse Dragging Parameters		Parameters for resizing and moving frames with the mouse.
29.4.3.8 ウィンドウ管理のパラメーター		ウィンドウマネージャーとの対話。
29.4.3.9 カーソルのパラメーター		カーソルの外見の制御。
29.4.3.10 フォントとカラーのパラメーター		フレームテキストにたいするフォントとカラー。
Positions
30.1 ポイント		編集タスクが行われる特別な位置。
30.2 モーション		ポイントの変更。
30.3 エクスカーション		一時的な移動とバッファーの変更。
30.4 ナローイング		バッファーの一部に編集を限定する。
Motion
30.2.1 文字単位の移動		文字単位での移動。
30.2.2 単語単位の移動		単語単位での移動。
30.2.3 バッファー終端への移動		バッファー先頭または終端への移動。
30.2.4 テキスト行単位の移動		テキスト行単位での移動。
30.2.5 スクリーン行単位の移動		表示される行単位での移動。
30.2.6 バランスのとれたカッコを越えた移動		リストやS式の解析による移動。
30.2.7 文字のスキップ		特定の集合に属す文字のスキップ。
Markers
31.1 マーカーの概要		マーカー構成要素と再配置方法。
31.2 マーカーのための述語		オブジェクトがマーカーか否かのテスト。
31.3 マーカーを作成する関数		空マーカーや特定箇所のマーカーの作成。
31.4 マーカーからの情報		マーカーのバッファーや文字位置を探す。
31.5 Marker 挿入タイプ		マーカーが指す位置への挿入時にマーカーを再配置する2つの方法。
31.6 マーカー位置の移動		新たなバッファーや位置にマーカーを移動する。
31.7 マーク		How the mark is implemented with a marker.
31.8 リージョン		How to access the region.
Text
32.1 ポイント周辺のテキストを調べる		ポイント付近のテキストを調べる。
32.2 バッファーのコンテンツを調べる		一般的な方法によってテキストを調べる。
32.3 テキストの比較		バッファーの部分文字列を比較する。
32.4 テキストの挿入		バッファーへの新たなテキストの追加。
32.5 ユーザーレベルの挿入コマンド		テキスト挿入のためのユーザーレベルコマンド。
32.6 テキストの削除		バッファーからテキストを削除する。
32.7 ユーザーレベルの削除コマンド		テキスト削除のためのユーザーレベルコマンド。
32.8 killリング		テキスト削除時にユーザーのためにそれを保存する場所。
32.9 アンドゥ		バッファーのテキストにたいする変更の取り消し。
32.10 アンドゥリストの保守		undo情報の有効と無効。情報をどれだけ保持するか制御する方法。
32.11 fill		明示的にフィルを行う関数。
32.12 fillのマージン		フィルコマンドにたいしてマージンを指定する方法。
32.13 Adaptive Fillモード		コンテキストからフィルプレフィクスを選択するAdaptive
32.14 オートfill		行ブレークにたいするauto-fillの実装方法。
32.15 テキストのソート		バッファーの一部をソートする関数。
32.16 列を数える		水平位置の計算とその使用方法。
32.17 インデント		インデントの挿入や調整のための関数。
32.18 大文字小文字の変更		バッファーの一部にたいするcase変換。
32.19 テキストのプロパティ		テキスト文字にたいするLispプロパティリストの追加。
32.20 文字コードの置き換え		与ええられた文字の出現箇所を置換する。
32.21 レジスター		レジスターの実装方法。レジスターに格納されたテキストや位置にアクセスする。
32.22 テキストの交換		バッファーの2つの部分を交換する。
32.24 圧縮されたデータの処理		圧縮データの扱い。
32.25 Base 64エンコーディング		Base64エンコーディングとの変換。
32.26 チェックサムとハッシュ		暗号ハッシュの計算。
32.27 GnuTLS Cryptography		Cryptographic algorithms imported from GnuTLS.
32.28 HTMLとXMLの解析		HTMLおよびXMLの解析。
32.29 グループのアトミックな変更		Installing several buffer changes atomically.
32.30 フックの変更		テキスト変更時に実行する関数の指定。
The Kill Ring
32.8.1 killリングの概念		killリング内のテキストがどのように見えるか。
32.8.2 killリングのための関数		テキストをkillする関数。
32.8.3 yank		yankが行われる方法。
32.8.4 yankのための関数		killリングにアクセスするコマンド。
32.8.5 低レベルのkillリング		killリングアクセス用の関数および変数。
32.8.6 killリングの内部		killリングのデータを保持する変数。
Indentation
32.17.1 インデント用のプリミティブ		インデントのカウントと挿入に使用される関数。
32.17.2 メジャーモードが制御するインデント		異なるモード用にインデントをカスタマイズする。
32.17.3 リージョン全体のインデント		リージョン内すべての行のインデント。
32.17.4 前行に相対的なインデント		前の行にもとづきカレント行をインデントする。
32.17.5 Adjustable Tab Stops		調整可能なタイプライター形式のタブストップ。
32.17.6 インデントにもとづくモーションコマンド		最初の非ブランク文字への移動。
Text Properties
32.19.1 テキストプロパティを調べる		単一の文字のプロパティを調べる。
32.19.2 テキストプロパティの変更		テキスト範囲のプロパティをセットする。
32.19.3 テキストプロパティの検索関数		プロパティが値を変更する場所の検索。
32.19.4 特殊な意味をもつプロパティ		特別な意味をもつ特定のプロパティ。
32.19.5 フォーマットされたテキストプロパティ		テキストのフォーマットを表すプロパティ。
32.19.6 テキストプロパティの粘着性		挿入されたテキストが隣接するテキストからプロパティを取得する方法。
32.19.7 テキストプロパティのlazyな計算		テキストが調べられる際のみ、ものぐさな方法でテキストプロパティを計算する。
32.19.8 クリック可能なテキストの定義		テキストプロパティを使用して、テキストリージョンがクリック時に何か行うようにする。
32.19.9 フィールドの定義と使用		バッファー内にフィールドを定義する`field`プロパティ。
32.19.10 なぜテキストプロパティはインターバルではないのか		テキストプロパティがLispから可視なテキスト間隔をもたない理由。
Parsing HTML and XML
32.28.1 Document Object Model		Access, manipulate and search the DOM.
Non-ASCII Characters
33.1 テキストの表現方法		Emacsがテキストを表す方法。
33.2 マルチバイト文字の無効化		マルチバイト使用を制御する。
33.3 テキスト表現の変換		ユニバイトとマルチバイトの相互変換。
33.4 表現の選択		バイトシーケンスをユニバイトやマルチバイトとして扱う。
33.5 文字コード		ユニバイトやマルチバイトが個々の文字のコードと関わる方法。
33.6 文字のプロパティ		文字の挙動と処理を定義する文字属性。
33.7 文字セット		利用可能な文字コード空間はさまざまな文字セットに分割される。
33.8 文字セットのスキャン		バッファーで使用されている文字セットは?
33.9 文字の変換		変換に使用される変換テーブル。
33.10 コーディングシステム		コーディングシステムはファイル保存のための変換である。
33.11 入力メソッド		入力メソッドによりユーザーは特別なキーボードなしで非ASCII文字を入力できる。
33.12 locale		POSIX localeとの対話。
Coding Systems
33.10.1 コーディングシステムの基本概念		基本的な概念。
33.10.2 エンコーディングとI/O		ファイル入出力関数がコーディングシステムを扱う方法。
33.10.3 Lispでのコーディングシステム		コーディングシステム名を処理する関数。
33.10.4 ユーザー選択のコーディングシステム		ユーザーにコーディングシステムの選択を求める。
33.10.5 デフォルトのコーディングシステム		デフォルトの選択の制御。
33.10.6 単一の操作にたいするコーディングシステムの指定		単一ファイル処理にたいして特定のコーディングシステムを要求する。
33.10.7 明示的なエンコードとデコード		入出力を伴わないテキストのエンコードおよびデコード。
33.10.8 端末I/Oのエンコーディング		端末入出力にたいするエンコーディングの使用。
Searching and Matching
34.1 文字列の検索		正確なマッチの検索。
34.2 検索と大文字小文字		case-independentまたはcase-significantな検索。
34.3 正規表現		文字列クラスの記述。
34.4 正規表現の検索		regexpにたいするマッチの検索。
34.5 POSIX正規表現の検索		最長マッチにたいするPOSIXスタイルのマッチ。
34.6 マッチデータ		文字列またはregexp検索後に、テキストがマッチした部分を見つける。
34.7 検索と置換		検索と置換を繰り返すコマンド。
34.8 編集で使用される標準的な正規表現		センテンスやページ等を探すために有用なregexp。
Regular Expressions
34.3.1 正規表現の構文		正規表現の記述ルール。
34.3.2 正規表現の複雑な例		正規表現構文の説明。
34.3.3 正規表現の関数		正規表現を操作する関数。
Syntax of Regular Expressions
34.3.1.1 正規表現内の特殊文字		正規表現内のスペシャル文字。
34.3.1.2 文字クラス		正規表現内で使用される文字クラス。
34.3.1.3 正規表現内のバッククラッシュ構造		正規表現内のバックスラッシュシーケンス。
The Match Data
34.6.1 マッチしたテキストの置換		マッチされた部分文字列の置換。
34.6.2 単純なマッチデータへのアクセス		特定の部分式開始箇所のような、マッチデータの単一アイテムへのアクセス。
34.6.3 マッチデータ全体へのアクセス		リストとしてマッチデータ全体に一度にアクセスする。
34.6.4 マッチデータの保存とリストア
Syntax Tables
35.1 構文テーブルの概念		構文テーブルの基本的概念。
35.2 構文記述子		文字がクラス分けされる方法。
35.3 構文テーブルの関数		構文テーブルを作成、調査、変更する方法。
35.4 構文プロパティ		テキストプロパティによる構文テーブルのオーバーライド。
35.5 モーションと構文		特定の構文による文字間の移動。
35.6 式のパース		構文テーブル使用によるバランスのとれた式の解析。
35.7 構文テーブルの内部		構文テーブルの情報が格納される方法。
35.8 カテゴリー		文字構文をクラス分けする別の手段。
Syntax Descriptors
35.2.1 構文クラスのテーブル
35.2.2 構文フラグ		各文字が所有できる追加のフラグ。
Parsing Expressions
35.6.1 パースにもとづくモーションコマンド		パースにより機能する移動関数。
35.6.2 ある位置のパース状態を調べる		ある位置の構文状態を判断する。
35.6.3 パーサー状態		Emacsが構文状態を表す方法。
35.6.4 低レベルのパース		指定されたリージョンを横断するパース。
35.6.5 パースを制御するためのパラメーター		パースに影響するパラメーター。
Abbrevs and Abbrev Expansion
36.1 abbrevテーブル		abbrevテーブルの作成と操作。
36.2 abbrevの定義		略語の指定とそれらの展開。
36.3 ファイルへのabbrevの保存
36.4 略語の照会と展開		展開の制御と展開サブルーチン。
36.5 標準的なabbrevテーブル		種々メジャーモードに使用されるabbrevテーブル。
36.6 abbrevプロパティー		abbrevプロパティの読み取りとセットを行う方法。どのプロパティが何の効果をもつか。
36.7 abbrevテーブルのプロパティー		abbrevテーブルプロパティの読み取りとセットを行う方法。どのプロパティが効果をもつか。
Threads
37.1 Basic Thread Functions		Basic thread functions.
37.2 Mutexes		Mutexes allow exclusive access to data.
37.3 Condition Variables		Inter-thread events.
Processes
38.1 サブプロセスを作成する関数		サブプロセスを開始する関数。
38.2 shell引数		shellに渡すために引数をクォートする。
38.3 同期プロセスの作成		同期サブプロセス使用の詳細。
38.4 非同期プロセスの作成		非同期サブプロセスの起動。
38.5 プロセスの削除		非同期サブプロセスの削除。
38.6 プロセスの情報		実行状態および他の属性へのアクセス。
38.7 プロセスへの入力の送信		非同期サブプロセスへの入力の送信。
38.8 プロセスへのシグナルの送信		非同期サブプロセスの停止、継続、割り込み。
38.9 プロセスからの出力の受信		非同期サブプロセスからの出力の収集。
38.10 センチネル: プロセス状態の変更の検知		プロセスの実行状態変更時に実行されるセンチネル。
38.11 exit前の問い合わせ		exitによりプロセスがkillされる場合に問い合わせるかどうか。
38.12 別のプセスへのアクセス		そのシステム上で実行中の別プロセスへのアクセス。
38.13 トランザクションキュー		サブプロセスとのトランザクションベースのコミュニケション。
38.14 ネットワーク接続		ネットワーク接続のopen。
38.15 ネットワークサーバー		Emacsによるネット接続のacceptを可能にするネットワークサーバー。
38.16 データグラム		UDPネットワーク接続。
38.17 低レベルのネットワークアクセス		接続およびサーバーを作成するための、より低レベルだがより汎用的な関数。
38.18 その他のネットワーク機能		ネット接続用の追加の関連関数。
38.19 シリアルポートとの対話		シリアルポートでのやり取り。
38.20 バイト配列のpackとunpack		bindatを使用したバイナリーデータのpackとunpack。
Receiving Output from Processes
38.9.1 プロセスのバッファー		デフォルトでは、出力はバッファーに送信される。
38.9.2 プロセスのフィルター関数		フィルター関数はプロセスからの出力を受け取る。
38.9.3 プロセス出力のデコード		フィルターはユニバイトおよびマルチバイトの文字列を取得できる。
38.9.4 プロセスからの出力を受け入れる		プロセスの出力到着まで待機する方法。
Low-Level Network Access
38.17.1 `make-network-process`		`make-network-process`’の使用。
38.17.2 ネットワークのオプション		更なるネットワーク接続の制御。
38.17.3 ネットワーク機能の可用性のテスト		使用中マシン上で動作するネットワーク機能を判断する。
Packing and Unpacking Byte Arrays
38.20.1 データレイアウトの記述
38.20.2 バイトのunpackとpackのための関数		unpack化とpack化を行う。
38.20.3 バイトのunpackとpackの例		bindat.elが行えることのサンプル。
Emacs Display
39.1 スクリーンのリフレッシュ		スクリーン上にあるすべてのもののクリアーと再描画。
39.2 強制的な再表示		再描画の強制。
39.3 切り詰め		長いテキストの折り畳みと折り返し。
39.4 エコーエリア		スクリーン最下部へのメッセージ表示。
39.5 警告のレポート		ユーザーへの警告メッセージの表示。
39.6 不可視のテキスト		バッファーのテキストの一部を隠す。
39.7 選択的な表示		バッファーのテキストの一部を隠す(旧来の方式)。
39.8 一時的な表示		自動的に消える表示。
39.9 オーバーレイ		オーバーレイを使用したバッファーの一部のハイライト。
39.10 表示されるテキストのサイズ		表示されたテキストの大きさ。
39.11 行の高さ		行の高さの制御。
39.12 フェイス		テキスト文字のグラフィカルスタイル(フォント、カラー等)を定義するフェイス。
39.13 フリンジ		ウィンドウフリンジの制御。
39.14 スクロールバー		Controlling scroll bars.
39.15 ウィンドウディバイダー		ウィンドウを視覚的に区別する。
39.16 `display`プロパティ		特別な表示機能の有効化。
39.17 イメージ		Emacsバッファー内でのイメージ表示。
39.19 ボタン		Emacsバッファー内へのイメージ表示クリック可能ボタン追加。
39.20 抽象的なディスプレー		オブジェクトコレクション用のEmacsウィジェット。
39.21 カッコの点滅		Emacsがマッチする開カッコを表示する方法。
39.22 文字の表示		Emacsがマッチする個々の文字を表示する方法。
39.23 ビープ		ユーザーへの可聴シグナル。
39.24 ウィンドウシステム		どのウィンドウシステムが使用されているか。
39.25 Tooltips		Tooltip display in Emacs.
39.26 双方向テキストの表示		アラビア語やペルシア語のような、双方向スクリプトの表示。
The Echo Area
39.4.1 エコーエリアへのメッセージの表示		エコーエリア内に明示的にテキストを表示する。
39.4.2 処理の進捗レポート		長時間の処理の進行状況をユーザーに知らせる。
39.4.3 `Messages`へのメッセージのロギング		ユーザー用にログされるエコーエリアメッセージ。
39.4.4 エコーエリアのカスタマイズ		エコーエリアの制御。
Reporting Warnings
39.5.1 警告の基礎		警告の概念と、それらを報告するための関数。
39.5.2 警告のための変数		プログラムが警告をカスタマイズするためにバインドする変数。
39.5.3 警告のためのオプション		ユーザーが警告の表示を制御するためにセットする変数。
39.5.4 遅延された警告		コマンド終了まで警告を延期する。
Overlays
39.9.1 オーバーレイの管理		オーバーレイの作成と変更。
39.9.2 オーバーレイのプロパティ		プロパティ読み取りおよびセットの方法。どのプロパティがスクリーン表示に何を行うか。
39.9.3 オーバーレイにたいする検索
Faces
39.12.1 フェイスの属性		フェイスとは?
39.12.2 フェイスの定義		フェイスを定義する方法。
39.12.3 フェイス属性のための関数		フェイス属性の確認およびセットを行う関数。
39.12.4 フェイスの表示		ある文字にたいして指定されたフェイスをEmacsが組み合わせる方法。
39.12.5 フェイスのリマップ		フェイスを別の定義にリマップする。
39.12.6 フェイスを処理するための関数		フェイスの定義、および確認する方法。
39.12.7 フェイスの自動割り当て		自動的にフェイスを割り当てるフック。
39.12.8 基本的なフェイス		デフォルトで定義されるフェイス。
39.12.9 フォントの選択		あるフェイスに最適なフォントを見つける。
39.12.10 フォントの照会		利用可能なフォント名とそれらの情報の照会。
39.12.11 フォントセット		フォントセット、それは文字セットの範囲を処理するフォントコレクションである。
39.12.12 低レベルのフォント表現		文字表示フォントのLisp表現。
Fringes
39.13.1 フリンジのサイズと位置		ウィンドウフリンジを置く場所を指定する。
39.13.2 フリンジのインジケーター		ウィンドウフリンジ内にインジケーターアイコンを表示する。
39.13.3 フリンジのカーソルFringe Cursors		右フリンジ内にカーソルを表示する。
39.13.4 フリンジのビットマップ		フリンジインジケーターにたいしてビットマップを指定する。
39.13.5 フリンジビットマップのカスタマイズ		フリンジ内で使用する独自ビットマップの指定。
39.13.6 オーバーレイ矢印		位置を示す矢印の表示。
The `display` Property
39.16.1 テキストを置換するディスプレー仕様		テキストを置換するディスプレイspec。
39.16.2 スペースの指定		指定された幅に1つのスペースを表示する。
39.16.3 スペースにたいするピクセル指定		ピクセル単位でスペースの幅または高さを指定する。
39.16.4 その他のディスプレー仕様		イメージの表示。高さ、スペーシング、その他のテキストプロパティの調整。
39.16.5 マージン内への表示		メインテキスト側面へのテキストまたはイメージの表示。
Images
39.17.1 イメージのフォーマット		サポートされるイメージフォーマット。
39.17.2 イメージのディスクリプタ		`:display`内で使用されるイメージの指定方法。
39.17.3 XBMイメージ		XBMフォーマット用の特別な機能。
39.17.4 XPMイメージ		XPMフォーマット用の特別な機能。
39.17.5 ImageMagickイメージ		ImageMagickを通じて利用できる特別な機能。
39.17.7 その他のイメージタイプ		サポートされるその他さまざまなフォーマット。
39.17.8 イメージの定義		後で使用するためにイメージを定義する便利な方法。
39.17.9 イメージの表示		一度定義されたイメージを表示するための便利な方法。
39.17.10 マルチフレームのイメージ		1つ以上のフレームを含むイメージ。
39.17.11 イメージキャッシュ		イメージ表示の内部的メカニズム。
Buttons
39.19.1 ボタンのプロパティ		特別な意味をもつボタンプロパティ。
39.19.2 ボタンのタイプ		ボタンのクラスにたいして一般的なプロパティを定義する。
39.19.3 ボタンの作成		Emacsバッファーへのボタンの追加。
39.19.4 ボタンの操作		ボタンプロパティの取得とセット。
39.19.5 ボタンのためのバッファーコマンド		ボタンにたいするバッファー規模のコマンドとバインディング。
Abstract Display
39.20.1 抽象ディスプレーの関数		Ewocパッケージ内の関数。
39.20.2 抽象ディスプレーの例		Ewocの使用例。
Character Display
39.22.1 通常の表示の慣習		文字の表示にたいする通常の慣習。
39.22.2 ディスプレーテーブル		ディスプレイテーブルの構成要素。
39.22.3 アクティブなディスプレーテーブル		使用するディスプレイテーブルをEmacsが選択する方法。
39.22.4 グリフ		グリフの定義方法とグリフの意味。
39.22.5 グリフ文字の表示		グリフなしの文字の描画方法。
Operating System Interface
40.1 Emacsのスタートアップ		Customizing Emacs startup processing.
40.2 Emacsからの脱出		(永久または一時的に)exitが機能する方法。
40.3 オペレーティングシステムの環境		システム名と種類の区別。
40.4 ユーザーの識別		そのユーザーの名前とユーザーIDを調べる。
40.5 時刻		カレント時刻の取得。
40.7 時刻の変換		時刻の数値形式からカレンダーデータへの変換と逆変換。
40.8 時刻のパースとフォーマット		時刻の数値形式からテキストへの変換と逆変換。
40.9 プロセッサーの実行時間		Emacsによる実行時間の取得。
40.10 時間の計算		時間の加減算、その他。
40.11 遅延実行のためのタイマー		特定時刻に関数を呼び出すためにターマーをセットする。
40.12 アイドルタイマー		Emacsが特定の時間の間アイドル時に関数を呼び出すためにタイマーをセットする。
40.13 端末の入力		端末入力へのアクセスと記録。
40.14 端末の出力		端末出力の制御と記録。
40.15 サウンドの出力		コンピューターのスピーカーでのサウンド再生。
40.16 X11キーシンボルの処理		Xウィンドウにたいするキーシンボルの操作。
40.17 batchモード		端末との対話なしでEmacsを実行する。
40.18 セッションマネージャー		Xセッション管理の保存とリストア。
40.19 デスクトップ通知
40.20 ファイル変更による通知		ファイル通知。
40.21 動的にロードされるライブラリー		サポートライブラリーのオンデマンドロード。
40.22 Security Considerations		Running Emacs in an unfriendly environment.
Emacsのスタートアップ
40.1.1 要約: スタートアップ時のアクション順序		スタートアップ時にEmacsが行うアクションの順序。
40.1.2 initファイル		initファイル読み込みの詳細。
40.1.3 端末固有の初期化		端末固有のLispファイルの読み込み方法。
40.1.4 コマンドライン引数		コマンドライン引数の処理とカスタマイズの方法。
Getting Out of Emacs
40.2.1 Emacsのkill		Emacsからの不可逆的なexit。
40.2.2 Emacsのサスペンド		Emacsからの可逆的なexit。
Terminal Input
40.13.1 入力のモード		入力の処理方法にたいするオプション。
40.13.2 入力の記録		直近またはすべての入力イベントのヒストリーの保存。
Preparing Lisp code for distribution
41.1 パッケージ化の基礎		Emacs Lispパッケージの基本的概念。
41.2 単純なパッケージ		単一.elファイルをパッケージする方法。
41.3 複数ファイルのパッケージ		複数ファイルをパッケージする方法。
41.4 パッケージアーカイブの作成と保守		パッケージアーカイブの保守。
Tips and Conventions
D.1 Emacs Lispコーディングの慣習		明快で堅牢なプログラムにたいする慣習。
D.2 キーバインディングの慣習		どのキーをどのプログラムにバインドすべきか。
D.3 Emacsプログラミングのヒント		Emacsコードを円滑にEmacsに適合させる。
D.4 コンパイル済みコードを高速化ためのヒント		コンパイル済みコードの実行を高速にする。
D.5 コンパイラー警告を回避するためのヒント		コンパイラー警告をオフにする。
D.6 ドキュメント文字列のヒント		読みやすいドキュメント文字列の記述。
D.7 コメント記述のヒント		コメント記述の慣習。
D.8 Emacsライブラリーのヘッダーの慣習		ライブラリーパッケージにたいする標準的なヘッダー。
GNU Emacs Internals
E.1 Emacsのビルド		ダンプ済みEmacsの作成方法。
E.2 純粋ストレージ		その場かぎりの事前ロードされたLisp関数を共有する。
E.3 ガーベージコレクション		Lispオブジェクトの使用されないスペースの回収。
E.4 Stack-allocated Objects		Temporary conses and strings on C stack.
E.5 メモリー使用量		これまでに作成されたLispオブジェクトの総サイズの情報。
E.6 C方言		What C variant Emacs is written in.
E.7 Emacsプリミティブの記述		Emacs用にCコードを記述する。
E.8 オブジェクトの内部		バッファー、ウィンドウ、プロセスのデーラフォーマット。
E.9 Cの整数型		How C integer types are used inside Emacs.
Object Internals
E.8.1 バッファーの内部		バッファー構造体の構成子。
E.8.2 ウィンドウの内部		ウィンドウ構造体の構成子。
E.8.3 プロセスの内部		プロセス構造体の構成子。

1 イントロダクション

GNU Emacsテキストエディターのほとんどの部分は、Emacs Lispと呼ばれるプログラミング言語で記述されています。新しいコードをEmacs Lispで記述して、このエディターの拡張としてインストールできます。しかしEmacs Lispは、単なる拡張言語を越える言語であり、それ自体で完全なコンピュータープログラミング言語です。他のプログラミング言語で行なうすべてのことに、この言語を使用できます。

Emacs Lispはエディターの中で使用するようにデザインされているので、テキストのスキャンやパースのための特別な機能をもち、同様にファイル、バッファー、ディスプレー、サブプロセスを処理する機能をもちます。Emacs Lispは編集機能と密に統合されています。つまり編集コマンドはLispプログラムから簡単に呼び出せる関数で、カスタマイズのためのパラメーターは普通のLisp変数です。

このマニュアルはEmacs Lispの完全な記述を試みます。初心者のためのEmacs Lispのイントロダクションは、Free Software Foundationからも出版されている、Bob ChassellのAn Introduction to Emacs Lisp Programmingを参照してください。このマニュアルは、Emacsを使用した編集に熟知していることを前提としています。これの基本的な情報については、The GNU Emacs Manualを参照してください。

おおまかに言うと、前の方のチャプターでは多くのプログラミング言語の機能にたいして、Emacs Lispでの対応する機能を説明し、後の方のチャプターではEmacs Lispに特異な機能や、編集に特化した関連する機能を説明します。

これは Emacs 26.1に対応したGNU Emacs Lisp Reference Manualです。

1.1 注意事項

このマニュアルは幾多のドラフトを経てきました。ほとんど完璧ではありますが、不備がないとも言えません。(ほとんどの特定のモードのように)それらが副次的であるとか、まだ記述されていないという理由により、カバーされていないトピックもあります。わたしたちがそれらを完璧に扱うことはできないので、いくつかの部分は意図的に省略しました。

このマニュアルは、それがカバーしている事柄については完全に正しくあるべきあり、故に特定の説明テキスト、チャプターやセクションの順番にたいしての批判にオープンであるべきです。判りにくかったり、このマニュアルでカバーされていない何かを学ぶためにソースを見たり実地から学ぶ必要があるなら、このマニュアルはおそらく訂正されるべきなのかもしれません。どうかわたしたちにそれを教えてください。

このマニュアルを使用するときは、間違いを見つけたらすぐに訂正を送ってください。関数または関数グループの単純な現実例を考えたときは、ぜひそれを記述して送ってください。それが妥当ならコメントでノード名と関数名や変数名を参照してください。あなたが訂正を求めるエディションのバージョンも示してください。

M-x report-emacs-bugを使用して、コメントや訂正を送ってください。

1.2 Lispの歴史

Lisp(LISt Processing language: リスト処理言語)は、MIT(Massachusetts Institute of Technology: マサチューセッツ工科大学)で、AI(artificial intelligence: 人工知能)の研究のために、1950年代末に最初に開発されました。Lisp言語の強力なパワーは、編集コマンドの記述のような、他の目的にも適っています。

長年の間に何ダースものLisp実装が構築されてきて、それらのそれぞれに特異な点があります。これらの多くは、1960年代にMITのProject MACで記述された、Maclispに影響を受けています。最終的に、Maclisp後裔の実装者は共同して、Common Lispと呼ばれる標準のLispシステムを開発しました。その間にMITのGerry SussmanとGuy Steeleにより、簡潔ながらとても強力なLisp方言の、Schemeが開発されました。

GNU Emacs LispはMaclispから多く、Common Lispから少し影響を受けています。Common Lispを知っている場合、多くの類似点に気づくでしょう。しかしCommon Lispの多くの機能は、GNU Emacsが要求するメモリー量を削減するために、省略または単純化されています。ときには劇的に単純化されているために、Common Lispユーザーは混乱するかもしれません。わたしたちは時折GNU Emacs LispがCommon Lispと異なるか示すでしょう。Common Lispを知らない場合、それについて心配する必要はありません。このマニュアルは、それ自体で自己完結しています。

cl-libライブラリーを通じて、Common Lispをかなりエミュレートできます。Overview in Common Lisp Extensionsを参照してください。

Emacs LispはSchemeの影響は受けていません。しかしGNUプロジェクトにはGuileと呼ばれるScheme実装があります。拡張が必要な新しいGNUソフトウェアーでは、Guileを使用します。

1.3 表記について

このセクションでは、このマニュアルで使用する表記規約を説明します。あなたはこのセクションをスキップして、後から参照したいと思うかもしれません。

1.3.1 用語について		このマニュアルで使用する用語の説明。
1.3.2 `nil`と`t`		シンボル`nil`と`t`の使用方法。
1.3.3 評価の表記		評価の例で使用するフォーマット。
1.3.4 プリントの表記		テキストのプリント例で使用するフォーマット。
1.3.5 エラーメッセージ		エラー例で使用するフォーマット。
1.3.6 バッファーテキストの表記		例のバッファー内容で使用するフォーマット。
1.3.7 説明のフォーマット		関数や変数などの説明にたいする表記。

1.3.1 用語について

このマニュアルでは、“Lispリーダー”および“Lispプリンター”という用語で、Lispのテキスト表現を実際のLispオブジェクトに変換したり、その逆を行なうLispルーチンを参照します。詳細については、プリント表現と読み取り構文を参照してください。あなた、つまりこのマニュアルを読んでいる人のことはプログラマーと考えて“あなた”と呼びます。“ユーザー”とは、あなたの記述したものも含めて、Lispプログラムを使用する人を指します。

Lispコードの例は、(list 1 2 3)のようなフォーマットです。メタ構文変数(metasyntactic variables)を表す名前や、説明されている関数の引数名前は、first-numberのようにフォーマットされています。

1.3.2 `nil`と`t`

Emacs Lispでは、シンボルnilには3つの異なる意味があります。1つ目は‘nil’という名前のシンボル、2つ目は論理値のfalse、3つ目は空リスト — つまり要素が0のリストです。変数として使用した場合、nilは常に値nilをもちます。

Lispリーダーに関する限り、‘()’と‘nil’は同一です。これらは同じオブジェクト、つまりシンボルnilを意味します。このシンボルを異なる方法で記述するのは、完全に人間の読み手を意図したものです。Lispリーダーが‘()’か‘nil’のどちらかを読み取った後は、プログラマーが実際にどちらの表現で記述したかを判断する方法はありません。

このマニュアルでは、空リストを意味することを強調したいときは()と記述し、論理値のfalseを意味することを強調したいときはnilと記述します。この慣習はLispプログラムで使用してもよいでしょう。

(cons 'foo ())                ; 空リストを強調
(setq foo-flag nil)           ; 論理値のfalseを強調

論理値が期待されているコンテキストでは、非nilはtrueと判断されます。しかし論理値のtrueを表す好ましい方法はtです。trueを表す値を選択する必要があり、他に選択の根拠がない場合はtを使用してください。シンボルtは、常に値tをもちます。

Emacs Lispでのnilとtは、常に自分自身を評価する特別なシンボルです。そのためプログラムでこれらを定数として使用する場合、クォートする必要はありません。これらの値の変更を試みると、結果はsetting-constantエラーとなります。変更不可な変数を参照してください。

Function: booleanp object: objectが2つの正規のブーリーン値(tかnil)のいずれかなら、非nilをリターンする。

1.3.3 評価の表記

評価できるLisp式のことをフォーム(form)と呼びます。フォームの評価により、これは結果として常にLispオブジェクトを生成します。このマニュアルの例では、これを‘⇒’で表します:

(car '(1 2))
     ⇒ 1

これは“(car '(1 2))を評価すると、1になる”と読むことができます。

フォームがマクロ呼び出しの場合、それは評価されるための新たなLispフォームに展開されます。展開された結果は‘→’で表します。わたしたちは展開されたフォームの評価し結果を示すこともあれば、示さない場合もあります。

(third '(a b c))
     → (car (cdr (cdr '(a b c))))
     ⇒ c

1つのフォームを説明するために、同じ結果を生成する別のフォームを示すこともあります。完全に等価な2つのフォームは、‘≡’で表します。

(make-sparse-keymap) ≡ (list 'keymap)

1.3.4 プリントの表記

このマニュアルの例の多くは、それらが評価されるときにテキストをプリントします。(*scratch*バッファーのような)Lisp Interactionバッファーでコード例を実行する場合、プリントされるテキストはそのバッファーに挿入されます。(関数eval-regionでの評価のように)他の方法でコード例を実行する場合、プリントされるテキストはエコーエリアに表示されます。

このマニュアルの例はプリントされるテキストがどこに出力されるかに関わらず、それを‘-|’で表します。フォームを評価することにより戻される値は、‘⇒’とともに後続の行で示します。

(progn (prin1 'foo) (princ "\n") (prin1 'bar))
     -| foo
     -| bar
     ⇒ bar

1.3.5 エラーメッセージ

エラーをシグナルする例もあります。これは通常、エコーエリアにエラーメッセージを表示します。エラーメッセージの行は‘error→’で始まります。‘error→’自体は、エコーエリアに表示されないことに注意してください。

(+ 23 'x)
error→ Wrong type argument: number-or-marker-p, x

1.3.6 バッファーテキストの表記

バッファー内容の変更を説明する例もあます。それらの例では、そのテキストのbefore(以前)とafter(以後)のバージョンを示します。それらの例では、バッファー内容の該当する部分を、ダッシュを用いた2行の破線(バッファー名を含む)で示します。さらに、‘∗’はポイントの位置を表します(もちろんポイントのシンボルはバッファーのテキストの一部ではなく、ポイントが現在配されている2つの文字の間の位置を表す)。

---------- Buffer: foo ----------
This is the ∗contents of foo.
---------- Buffer: foo ----------

(insert "changed ")
     ⇒ nil
---------- Buffer: foo ----------
This is the changed ∗contents of foo.
---------- Buffer: foo ----------

1.3.7 説明のフォーマット

このマニュアルでは関数(function)、変数(variable)、コマンド(command)、ユーザーオプション(user option)、スペシャルフォーム(special form)を、統一されたフォーマットで記述します。記述の最初の行には、そのアイテムの名前と、もしあれば引数(argument)が続きます。そのアイテムの属するカテゴリー(function、variableなど)は、行の先頭に表示します。それ以降の行は説明行で、例を含む場合もあります。

1.3.7.1 関数の説明例

関数の記述では、関数の名前が最初に記述されます。同じ行に引数の名前のリストが続きます。引数の値を参照するために、引数の名前は記述の本文にも使用されます。

引数リストの中にキーワード&optionalがある場合、その後の引数が省略可能であることを示します(省略された引数のデフォルトはnil)。その関数を呼び出すときは、&optionalを記述しないでください。

キーワード&rest(これの後には1つの引数名を続けなければならない)は、その後に任意の引数を続けることができることを表します。&restの後に記述された引数名の値には、その関数に渡された残りのすべての引数がリストとしてセットされます。この関数を呼び出すときは、&restを記述しないでください。

以下はfooという架空の関数(function)の説明です:

Function: foo integer1 &optional integer2 &rest integers

関数fooはinteger2からinteger1を減じてから、その結果に残りすべての引数を加える。integer2が与えられなかった場合、デフォルトして数値19が使用される。

(foo 1 5 3 9)
     ⇒ 16
(foo 5)
     ⇒ 14

より一般的には、

(foo w x y…)
≡
(+ (- x w) y…)

慣例として引数の名前には、(たとえばinteger、integer1、bufferのような)期待されるタイプ名が含まれます。(buffersのような)複数形のタイプは、しばしばその型のオブジェクトのリストを意味します。objectのような引き数名は、それが任意の型であることを表します(EmacsオブジェクトタイプのリストはLispのデータ型を参照)。他の名前をもつ引数(たとえばnew-file)はその関数に固有の引数で、関数がドキュメント文字列をもつ場合、引数のタイプはその中で説明されるべきです(ドキュメントを参照)。

&optionalや&restにより修飾される引数のより完全な説明は、ラムダ式を参照してください。

コマンド(command)、マクロ(macro)、スペシャルフォーム(special form)の説明も同じフォーマットですが、‘Function’が‘Command’、‘Macro’、‘Special Form’に置き換えられます。コマンドはとは単に、インタラクティブ(interactive: 対話的)に呼び出すことができる関数です。マクロは関数とは違う方法(引数は評価されない)で引数を処理しますが、同じ方法で記述します。

マクロとスペシャルフォームにたいする説明には、特定のオプション引数や繰り替えされる引数のために、より複雑な表記が使用されます。なぜなら引数リストが、より複雑な方法で別の引数に分離されるからです。‘[optional-arg]’はoptional-argがオプションであることを意味し、‘repeated-args…’は0個以上の引数を表します。カッコ(parentheses)は、複数の引数をリスト構造の追加レベルにグループ化するのに使用されます。以下は例です:

Special Form: count-loop (var [from to [inc]]) body…

この架空のスペシャルフォームは、 bodyフォームを実行してから変数varをインクリメントするループを実装します。最初の繰り返しでは変数は値fromをもちます。以降の繰り返しでは、変数は1(incが与えられた場合はinc)増分されます。varがtoに等しい場合、bodyを実行する前にループをexitします。以下は例です:

(count-loop (i 0 10)
  (prin1 i) (princ " ")
  (prin1 (aref vector i))
  (terpri))

fromとtoが省略された場合、ループを実行する前にvarにnilがバインドされ、繰り返しの先頭においてvarが非nilの場合は、ループをexitします。以下は例です:

(count-loop (done)
  (if (pending)
      (fixit)
    (setq done t)))

このスペシャルフォームでは、引数fromとtoはオプションですが、両方を指定するか未指定にするかのいずれかでなければなりません。これらの引数が与えられた場合には、オプションでincも同様に指定することができます。これらの引数は、フォームのすべての残りの要素を含むbodyと区別するために、引数varとともにリストにグループ化されます。

1.3.7.2 変数の説明例

変数(variable)とは、オブジェクトにバインド(bind)される名前です(セット(set)とも言う)。変数がバインドされたオブジェクトのことを値(value)と呼びます。このような場合には、その変数が値をもつという言い方もします。ほとんどすべての変数はユーザーがセットすることができますが、特にユーザーが変更できる特定の変数も存在し、これらはユーザーオプション(user options)と呼ばれます。通常の変数およびユーザーオプションは、関数と同様のフォーマットを使用して説明されますが、それらには引数がありません。

以下は架空の変数electric-future-mapの説明です。

Variable: electric-future-map: この変数の値はElectric Command Futureモードで使用される完全なキーマップである。このマップ内の関数により、まだ実行を考えていないコマンドの編集が可能になる。

ユーザーオプションも同じフォーマットをもちますが、‘Variable’が‘User Option’に置き換えられます。

1.4 バージョンの情報

以下の機能は、使用しているEmacsに関する情報を提供します。

Command: emacs-version &optional here

この関数は実行しているEmacsのバージョンを説明する文字列をreturnすす。これはバグレポートにこの文字列を含めるときに有用である。

(emacs-version)
  ⇒ "GNU Emacs 26.1 (build 1, x86_64-unknown-linux-gnu,
             GTK+ Version 3.16) of 2017-06-01"

hereが非nilならテキストをバッファーのポイントの前に挿入して、nilをリターンする。この関数がインタラクティブに呼び出すと、同じ情報をエコーエリアに出力する。プレフィクス引数を与えると、hereが非nilになる。

Variable: emacs-build-time

The value of this variable indicates the time at which Emacs was built. It is a list of four integers, like the value of current-time (see section 時刻), or is nil if the information is not available.

emacs-build-time
     ⇒ (20614 63694 515336 438000)

Variable: emacs-version: The value of this variable is the version of Emacs being run. It is a string such as "26.1". A value with three numeric components, such as "26.0.91", indicates an unreleased test version. (Prior to Emacs 26.1, the string includes an extra final component with the integer that is now stored in emacs-build-number; e.g., "25.1.1".)

Variable: emacs-major-version: Emacsのメジャーバージョン番号を示す整数。Emacs 23.1では値は23。

Variable: emacs-minor-version: Emacsのマイナーバージョン番号を示す整数。Emacs 23.1では値は1。

Variable: emacs-build-number: An integer that increments each time Emacs is built in the same directory (without cleaning). This is only of relevance when developing Emacs.

1.5 謝辞

このマニュアルは当初、Robert Krawitz、Bil Lewis、Dan LaLiberte、Richard M. Stallman、Chris Welty、およびGNUマニュアルグループのボランティアにより、数年を費やして記述されました。Robert J. Chassellはこのマニュアルのレビューと編集をDefense Advanced Research Projects Agency、ARPA Order 6082のサポートのもとに手助けしてくれ、Computational Logic, IncのWarren A. Hunt, Jr.によりアレンジされました。それ以降も追加のセクションがMiles Bader、Lars Brinkhoff、Chong Yidong、Kenichi Handa、Lute Kamstra、Juri Linkov、Glenn Morris、Thien-Thi Nguyen、Dan Nicolaescu、Martin Rudalics、Kim F. Storm、Luc Teirlinck、Eli Zaretskii、およびその他の人たちにより記述されました。

Drew Adams、Juanma Barranquero、Karl Berry、Jim Blandy、Bard Bloom、Stephane Boucher、David Boyes、Alan Carroll、Richard Davis、Lawrence R. Dodd、Peter Doornbosch、David A. Duff、Chris Eich、Beverly Erlebacher、David Eckelkamp、Ralf Fassel、Eirik Fuller、Stephen Gildea、Bob Glickstein、Eric Hanchrow、Jesper Harder、George Hartzell、Nathan Hess、Masayuki Ida、Dan Jacobson、Jak Kirman、Bob Knighten、Frederick M. Korz、Joe Lammens、Glenn M. Lewis、K. Richard Magill、Brian Marick、Roland McGrath、Stefan Monnier、Skip Montanaro、John Gardiner Myers、Thomas A. Peterson、Francesco Potortì、Friedrich Pukelsheim、Arnold D. Robbins、Raul Rockwell、Jason Rumney、Per Starbäck、Shinichirou Sugou、Kimmo Suominen、Edward Tharp、Bill Trost、Rickard Westman、Jean White、Eduard Wiebe、Matthew Wilding、Carl Witty、Dale Worley、Rusty Wright、David D. Zuhnにより訂正が提供されました。

より完全な貢献者のリストは、Emacsソースリポジトリーの関連する変更ログエントリーを参照してください。

2 Lispのデータ型

Lispのオブジェクト(object)とは、Lispプログラムから操作されるデータです。型(type)やデータ型(data type)とは、可能なオブジェクトの集合を意味します。

すべてのオブジェクトは少なくとも1つの型に属します。同じ型のオブジェクトは同様な構造をもち、通常は同じコンテキストで使用されます。型を重複してもつことができ、オブジェクトは複数の型に属することができます。その結果として、あるオブジェクトが特定の型に属するかどうかを尋ねることはできますが、オブジェクトがその型だけに属するかどうかは決定できません。

A few fundamental object types are built into Emacs. These, from which all other types are constructed, are called primitive types. Each object belongs to one and only one primitive type. These types include integer, float, cons, symbol, string, vector, hash-table, subr, byte-code function, and record, plus several special types, such as buffer, that are related to editing. (See section 編集用の型.)

プリミティブ型にはそれぞれ、オブジェクトがその型のメンバーかどうかのチェックを行なうために、それぞれ対応するLisp関数があります。

他の多くの言語とは異なり、Lispのオブジェクトは自己記述(self-typing)的です。オブジェクトのプリミティブ型は、オブジェクト自体に暗に含まれます。たとえばオブジェクトがベクターなら、それを数字として扱うことはできません。Lispはベクターが数字でないことを知っているのです。

多くの言語では、プログラマーは各変数にたいしてデータ型を宣言しなければならず、コンパイラーは型を知っていますが、データの中に型はありません。Emacs Lispには、このような型宣言はありません。Lisp変数は任意の型の値をもつことができ、変数に保存した値と型を記憶します(実際には特定の型の値だけをもつことができる少数のEmacs Lisp変数がある。値を制限された変数を参照されたい)。

このチャプターでは、GNU Emacs Lispの各標準型の意味、プリント表現(printed representation)、入力構文(read syntax)を説明します。これらのデータ型を使用する方法についての詳細は、以降のチャプターを参照してください。

2.1 プリント表現と読み取り構文		Lispオブジェクトがテキストとして表現される方法。
2.2 コメント		コメントとコメント書式の慣例。
2.3 プログラミングの型		すべてのLispシステムに存在する型。
2.4 編集用の型		Emacs固有の型。
2.5 循環オブジェクトの読み取り構文		循環構造にたいする入力構文。
2.6 型のための述語		型に関連するテスト。
2.7 同等性のための述語		2つのオブジェクトが等しいかのテスト。

2.1 プリント表現と読み取り構文

オブジェクトのプリント表現(printed representation)とは、オブジェクトにたいしてLispプリンター(関数prin1)が生成する出力のフォーマットです。すべてのデータ型は一意なプリント表現をもちます。オブジェクトの入力構文(read syntax)とは、オブジェクトにたいしてLispリーダー(関数read)が受け取る入力のフォーマットです。これは一意である必要はありません。多くの種類のオブジェクトが複数の構文をもちます。Lispオブジェクトの読み取りとプリントを参照してください。

ほとんどの場合、オブジェクトのプリント表現が、入力構文としても使用されます。しかしLispプログラム内の定数とすることに意味が無いいくつかの型には、入力構文がありません。これらのオブジェクトはハッシュ表記(hash notation)でプリントされ、‘#<’、説明的な文字列(典型的には型名にオブジェクトの名前を続けたもの)、‘>’で構成される文字列です。たとえば:

(current-buffer)
     ⇒ #<buffer objects.texi>

ハッシュ表記は読み取ることができないので、Lispリーダーは‘#<’に遭遇すると常にエラーinvalid-read-syntaxをシグナルします。

他の言語では式はテキストであり、これ以外の形式はありません。Lispでは式は第一にまずLispオブジェクトであって、オブジェクトの入力構文であるテキストは副次的なものに過ぎません。たいていこの違いを強調する必要はありませんが、このことを心に留めておかないとたまに混乱することがあるでしょう。

インタラクティブに式を評価するとき、Lispインタープリターは最初にそれのテキスト表現を読み取り、Lispオブジェクトを生成してからそのオブジェクトを評価します(評価を参照)。しかし評価と読み取りは別の処理です。読み取りによりテキストにより表現されたLispオブジェクトを読み取り、Lispオブジェクトがリターンされます。後でオブジェクトは評価されるかもしれないし、評価されないかもしれません。オブジェクトを読み取るための基本的な関数readの説明は、入力関数を参照してください。

2.2 コメント

コメント(comment)はプログラム中に記述されたテキストであり、そのプログラムを読む人間ためだけに存在するもので、プログラムの意味には何の影響ももちません。Lispではそれが文字列や文字定数にある場合をのぞき、セミコロン(‘;’)でコメントが開始されます。行の終端までがコメントになります。Lispリーダーはコメントを破棄します。コメントはLispシステム内でプログラムを表すLispオブジェクトの一部にはなりません。

‘#@count’構成は、次のcount個の文字をスキップします。これはプログラムにより生成されたバイナリーデータを含むコメントにたいして有用です。Emacs Lispバイトコンパイラーは出力ファイルにこれを使用します(バイトコンパイルを参照)。しかしソースファイル用ではありません。

コメントのフォーマットにたいする慣例は、コメント記述のヒントを参照してください。

2.3 プログラミングの型

Emacs Lispには2種類の一般的な型があります。1つはLispプログラミングに関わるもので、もう1つは編集に関わるものです。前者はさまざまな形で多くのLisp実装に存在します。後者はEmacs Lispに固有です。


2.3.1 整数型		小数部のない数字。
2.3.2 浮動小数点数型		広い範囲をもつ、小数部をもつ数字。
2.3.3 文字型		文字、数字、コントロール文字にたいする表現。
2.3.4 シンボル型		関数、変数、プロパティーリストを参照する、一意に識別される多目的オブジェクト。
2.3.5 シーケンス型		リストと配列はどちらもシーケンスに分類される。
2.3.6 コンスセルとリスト型		コンスセル、および(コンスセルにより作られる)リスト。
2.3.7 配列型		配列には文字列とベクターが含まれる。
2.3.8 文字列型		(効率的な)文字の配列。
2.3.9 ベクター型		1次元の配列。
2.3.10 文字テーブル型		文字によりインデックスされる1次元の疎な配列。
2.3.11 ブールベクター型		`t`と`nil`からなる1次元の配列。
2.3.12 ハッシュテーブル型		非常に高速な参照用のテーブル。
2.3.13 関数型		他の場所から呼び出せる実行可能なコード断片。
2.3.14 マクロ型		より基本的だが少し見栄えの悪い、式を他の式に展開する手法。
2.3.15 プリミティブ関数型		Lispから呼び出せるCで記述された関数。
2.3.16 バイトコード関数型		Lispで記述されてコンパイルされた関数。
2.3.17 Record Type		Compound objects with programmer-defined types.
2.3.18 Type Descriptors		Objects holding information about types.
2.3.19 autoload型		頻繁に使用されない関数を自動的にロードするために使用される型。
2.3.20 Finalizer Type		オブジェクトが到達不能になった際に実行するコード。

2.3.1 整数型

整数の値の範囲はマシンに依存します、最小のレンジは-536,870,912から536,870,911(30ビットでは -2**29 から 2**29 - 1) ですが、多くのマシンはこれより広い範囲を提供します。Emacs Lispの数学関数は整数のオーバーフローをチェックしません。したがってEmacsのh整数が30ビットの場合、(1+ 536870911)は-536,870,912になります。

整数にたいする入力構文は、(10を基数とする)数字のシーケンスで、オプションで先頭に符号、最後にピリオドがつきます。Lispインタープリターにより生成されるプリント表現には、先頭の ‘+’や最後の‘.’はありません。

-1               ; 整数の-1
1                ; 整数の1
1.               ; これも整数の1
+1               ; これも整数の1

特別な例外として、数字シーケンスが有効なオブジェクトとしては大きすたり小さすぎる整数を指定する場合、Lispリーダーはそれを浮動小数点数(浮動小数点数型を参照)として読み取ります。たとえば、Emacsの整数が30ビットの場合、536870912は浮動小数点数の536870912.0として読み取られます。

詳細は数値を参照してください。

2.3.2 浮動小数点数型

浮動小数点数は、コンピューターにおける科学表記に相当するものです。浮動小数点数を10の指数をともなう有理数として考えることができます。正確な有効桁数と可能な指数はマシン固有です。Emacsは値の保存にCデータ型のdoubleを使用し、内部的には10の指数ではなく、2の指数として記録します。

浮動小数点数のプリント表現には、(後に最低1つの数字をともなう)小数点と、指数のどちらか一方、または両方が必要です。たとえば‘1500.0’、‘+15e2’、‘15.0e+2’、‘+1500000e-3’、‘.15e4’は、いずれも浮動小数点数の1500を記述し、これらはすべて等価です。

詳細は数値を参照してください。

2.3.3 文字型

Emacs Lispでの文字(character)は、整数以外の何者でもありません。言い換えると、文字は文字コードで表現されます。たとえば文字Aは、整数の65として表現されます。

プログラムで文字を個別に使用するのは稀であり、文字のシーケンスとして構成される文字列(strings)として扱われるのがより一般的です。文字列型を参照してください。

文字列やバッファーの中の文字は、現在のところ0から4194303の範囲 — つまり22ビットに制限されています(文字コードを参照)。0から127のコードはASCIIコードで、残りは非ASCIIです(非ASCII文字を参照)。キーボード入力を表す文字はコントロール(Control)、メタ(Meta)、シフト(Shift)などの修飾キーをエンコードするために、より広い範囲をもちます。

文字から可読なテキスト記述を生成する、メッセージ用の特別な関数が存在します。ヘルプメッセージの文字記述を参照してください。

2.3.3.1 基本的な文字構文

文字は実際には整数なので、文字のプリント表現は10進数です。文字にたいする入力構文も利用可能ですが、Lispプログラムでこの方法により文字を記述するのは、明解なプログラミングではありません。文字にたいしては、Emacs Lispが提供する、特別な入力構文を常に使用するべきです。これらの構文フォーマットはクエスチョンマークで開始されます。

英数字にたいする通常の入力構文は、クエスチョンマークと、その後にその文字を記述します。したがって文字Aは‘?A’、文字Bは‘?B’、文字aは‘?a’となります。

たとえば:

?Q ⇒ 81     ?q ⇒ 113

You can use the same syntax for punctuation characters. However, if the punctuation character has a special syntactic meaning in Lisp, you must quote it with a ‘\’. For example, ‘?\(’ is the way to write the open-paren character. Likewise, if the character is ‘\’, you must use a second ‘\’ to quote it: ‘?\\’.

Ctrl+g(control-g)、バックスペース(backspace)、タブ(tab)、改行(newline)、垂直タブ(vertical tab)、フォームフィード(formfeed)、スペース(space)、キャリッジリターン(return)、デリート(del)、エスケープ(escape)はそれぞれ‘?\a’、‘?\b’、‘?\t’、‘?\n’、‘?\v’、‘?\f’、‘?\s’、‘?\r’、‘?\d’、‘?\e’と表すことができます(後にダッシュのついた‘?\s’は違う意味をもつ — これは後続の文字にたいしてスーパーによる修飾を適用する)。したがって、

?\a ⇒ 7                 ; control-g、C-g
?\b ⇒ 8                 ; バックスペース、BS、C-h
?\t ⇒ 9                 ; タブ、TAB、C-i
?\n ⇒ 10                ; 改行、C-j
?\v ⇒ 11                ; 垂直タブ、C-k
?\f ⇒ 12                ; フォームフィード文字、C-l
?\r ⇒ 13                ; キャリッジリターン、RET、C-m
?\e ⇒ 27                ; エスケープ文字、ESC、C-[
?\s ⇒ 32                ; スペース文字、SPC
?\\ ⇒ 92                ; バックスラッシュ文字、\
?\d ⇒ 127               ; デリート文字、DEL

バックスラッシュがエスケープ文字の役割を果たすので、これらのバックスラッシュで始まるシーケンスはエスケープシーケンス(escape sequences)とも呼ばれます。この用語法は文字ESCとは関係ありません。‘\s’は文字定数としての使用を意図しており、文字定数の内部では単にスペースを記述します。

A backslash is allowed, and harmless, preceding any character without a special escape meaning; thus, ‘?\+’ is equivalent to ‘?+’. There is no reason to add a backslash before most characters. However, you must add a backslash before any of the characters ‘()[]\;"’, and you should add a backslash before any of the characters ‘|'`#.,’ to avoid confusing the Emacs commands for editing Lisp code. You can also add a backslash before whitespace characters such as space, tab, newline and formfeed. However, it is cleaner to use one of the easily readable escape sequences, such as ‘\t’ or ‘\s’, instead of an actual whitespace character such as a tab or a space. (If you do write backslash followed by a space, you should write an extra space after the character constant to separate it from the following text.)

2.3.3.2 一般的なエスケープ構文

特に重要なコントロール文字にたいする特別なエスケープシーケンスに加えて、Emacsは非ASCIIテキスト文字の指定に使用できる、何種類かのエスケープ構文を提供します。

You can specify characters by their Unicode names, if any. ?\N{NAME} represents the Unicode character named NAME. Thus, ‘?\N{LATIN SMALL LETTER A WITH GRAVE}’ is equivalent to ?à and denotes the Unicode character U+00E0. To simplify entering multi-line strings, you can replace spaces in the names by non-empty sequences of whitespace (e.g., newlines).
You can specify characters by their Unicode values. ?\N{U+X} represents a character with Unicode code point X, where X is a hexadecimal number. Also, ?\uxxxx and ?\Uxxxxxxxx represent code points xxxx and xxxxxxxx, respectively, where each x is a single hexadecimal digit. For example, ?\N{U+E0}, ?\u00e0 and ?\U000000E0 are all equivalent to ?à and to ‘?\N{LATIN SMALL LETTER A WITH GRAVE}’. The Unicode Standard defines code points only up to ‘U+10ffff’, so if you specify a code point higher than that, Emacs signals an error.
You can specify characters by their hexadecimal character codes. A hexadecimal escape sequence consists of a backslash, ‘x’, and the hexadecimal character code. Thus, ‘?\x41’ is the character A, ‘?\x1’ is the character C-a, and ?\xe0 is the character à (a with grave accent). You can use any number of hex digits, so you can represent any character code in this way.
You can specify characters by their character code in octal. An octal escape sequence consists of a backslash followed by up to three octal digits; thus, ‘?\101’ for the character A, ‘?\001’ for the character C-a, and ?\002 for the character C-b. Only characters up to octal code 777 can be specified this way.

これらのエスケープシーケンスは文字列内でも使用されます。文字列内の非ASCII文字を参照してください。

2.3.3.3 コントロール文字構文

他の入力構文を使用してコントロール文字を表すことができます。これは後にバックスラッシュ、カレット、対応する非コントロール文字(大文字か小文字)をともなうクエスチョンマークから構成されます。たとえば‘?\^I’と‘?\^i’はどちらも、値が9である文字C-iの有効な入力構文です。

‘^’のかわりに‘C-’を使用することもできます。したがって‘?\C-i’は‘?\^I’や‘?\^i’と等価です。

?\^I ⇒ 9     ?\C-I ⇒ 9

文字列やバッファーの中ではASCIIのコントロール文字だけが許されますが、キーボード入力にたいしては‘C-’により任意の文字をコントロール文字にすることができます。これらの非ASCIIのコントロール文字にたいするコントロール文字には非コントロール文字にたいするコードと同様に、2**26 ビットが含まれます。通常のテキスト端末には非ASCIIコントロール文字を生成する方法がありませんが、Xやその他のウィンドウシステムを使用すれば簡単に生成することができます。

歴史的な理由により、EmacsはDEL文字を?のコントロール文字として扱います:

?\^? ⇒ 127     ?\C-? ⇒ 127

結果として、Xでは有意な入力文字であるControl-?文字を、‘\C-’を使用して表現することは今のところできません。さまざまなLispファイルがこの方法でDELを参照するので、これを変更するのは簡単ではないのです。

コントロール文字の表現はファイルや文字列内で見ることができますが、わたしたちは‘^’構文を推奨します。キーボード入力にたいするコントロール文字に好ましいのは、‘C-’構文です。どちらを使用するかはプログラムの意味に影響しませんが、プログラムを読む人の理解を助けるでしょう。

2.3.3.4 メタ文字構文

メタ文字(meta character)とは、META修飾キーとともにタイプされた文字です。そのような文字を表す整数には 2**27 のビットがセットされています。基本的な文字コードの広い範囲を利用可能にするために、メタやその他の修飾にたいしては上位ビットを使用します。

文字列では、メタ文字を示すASCII文字に、 2**7 ビットが付加されます。したがって文字列に含めることができるメタ文字のコードは1から255の範囲となり、メタ文字は通常のASCII文字のメタ修飾されたバージョンとなります。文字列内でのMETA処理の詳細については、文字列内へのキーボードイベントの配置を参照してください。

メタ文字の入力構文には‘\M-’を使用します。たとえば‘?\M-A’はM-Aを意味します。8進文字コード(以下参照)や、‘\C-’、その他の文字にたいする他の構文とともに‘\M-’を使用できます。したがって、M-Aは‘?\M-A’や‘?\M-\101’と記述できます。同様にC-M-bは‘?\M-\C-b’、‘?\C-\M-b’、‘?\M-\002’と記述することができます。

2.3.3.5 その他の文字修飾ビット

グラフィック文字(graphic character)のcaseは文字コードで示されます。たとえばASCIIでは、文字‘a’と文字‘A’は区別されます。しかしASCIIにはコントロール文字が大文字なのか小文字なのかを表現する方法がありません。コントロール文字がタイプされたときシフトキーが使用されたかを示すために、Emacsは 2**25 のビットを使用します。この区別はX端末や、その他の特別な端末を使用しているときだけ可能です。通常のテキスト端末は、これらの違いを報告しません。シフトをあらわすビットのためのLisp構文は‘\S-’です。したがって‘?\C-\S-o’や‘?\C-\S-O’は、Shift+Ctrl+o文字を表します。

Xウィンドウシステムは文字にセットするために、他にも3つ修飾ビット — ハイパー(hyper)、スーパー(super)、アルト(alt)を定義します。これらのビットにたいする構文は、‘\H-’、‘\s-’、‘\A-’です(これらのプレフィクスでは、caseは意味がある)。したがって‘?\H-\M-\A-x’はAlt-Hyper-Meta-xを表します(‘-’が後にない‘\s’はスペース文字を表すことに注意)。数値としてはビット値2**22はアルト、2**23はスーパー、2**24はハイパーです。

2.3.4 シンボル型

GNU Emacs Lispでのシンボル(symbol)とは、名前をもつオブジェクトです。シンボル名は、そのシンボルのプリント表現としての役割があります。Lispの通常の使用では、1つのobarray(シンボルの作成とinternを参照)により、シンボル名は一意です — 2つのシンボルが同じ名前をもつことはありません。

シンボルは変数や関数名としての役割、プロパティーリストを保持する役割をもつことができます。データ構造内にそのようなシンボルが存在することが確実に認識できるように、他のすべてのLispオブジェクトから区別するためだけの役割をもつ場合もあります。与えられたコンテキストにおいて、通常はこれらのうちの1つの使用だけが意図されます。しかし3つすべての方法で、1つのシンボルを独立して使用することもできます。

名前がコロン(‘:’)で始まるシンボルはキーワードシンボル(keyword symbol)と呼ばれます。これらのシンボルは自動的に定数として振る舞い、通常は未知のシンボルといくつかの特定の候補を比較することだけに使用されます。変更不可な変数を参照してください。

シンボル名にはどんな文字でも含めることができます。ほとんどのシンボル名は英字、数字、‘-+=*/’などの区切り文字で記述されます。このような名前には特別な区切り文字は必要ありません。名前が数字のように見えない限り、名前にはどのような文字も使用できます(名前が数字のように見える場合は、名前の先頭に‘\’を記述して強制的にシンボルとして解釈させる)。文字‘_~!@$%^&:<>{}?’はあまり使用されませんが、これらも特別な句読点文字を必要としません。他の文字も、バックスラッシュでエスケープすることにより、シンボル名に含めることができます。しかし文字列内でのバックスラッシュの使用とは対照的に、シンボル名でのバックスラッシュは、バックスラッシュの後の1文字をエスケープするだけです。たとえば文字列内では、‘\t’はタブ文字を表します。しかしシンボル名の中では、‘\t’は英字‘t’をクォートするに過ぎません。名前にタブ文字をもつシンボルを記述するには、(バックスラッシュを前置した)実際のタブを使用しなければなりません。しかし、そのようなことを行なうことは稀です。

Common Lispに関する注意:Common Lispでは明示的にエスケープされない限り、小文字は常に大文字に“フォールド(folded)”される。Emacs Lispでは大文字と小文字は区別される。

以下はシンボル名の例です。4つ目の例の中の‘+’は、シンボルが数字として読み取られるのを防ぐためにエスケープされていることに注意してください。6つ目の例では、名前の残りの部分により数字としては不正なのでエスケープの必要はありません。

foo                 ; ‘foo’という名前のシンボル
FOO                 ; ‘foo’とは別の、‘FOO’という名前のシンボル

1+                  ; ‘1+’という名前のシンボル
                    ;   (整数の‘+1’ではない)

\+1                 ; ‘+1’という名前のシンボル
                    ;   (判読しにくい名前)

\(*\ 1\ 2\)         ; ‘(* 1 2)’という名前のシンボル(悪い名前)
+-*/_~!@$%^&=:<>{}  ; ‘+-*/_~!@$%^&=:<>{}’という名前のシンボル
                    ;   これらの文字のエスケープは不要

シンボル名がプリント表現としての役割をもつというルールの例外として、‘##’があります。これは、名前が空文字列のinternされたシンボルのプリント表現です。さらに‘#:foo’は、internされていないfooという名前のシンボルにたいするプリント表現です(通常、Lispリーダーはすべてのシンボルをinternする。シンボルの作成とinternを参照されたい)。

2.3.5 シーケンス型

シーケンス(sequence)とは、要素の順序セットを表現するLispオブジェクトです。Emacs Lispには2種類のシーケンス — リスト(lists)と配列(arrays)があります。

リストはもっとも一般的に使用されるシーケンスです。リストは任意の型の要素を保持でき、要素の追加と削除により簡単に長さを変更できます。リストについては、次のサブセクションを参照してください。

配列は固定長のシーケンスです。配列はさらに文字列(strings)、ベクター(vectors)、文字テーブル(char-tables)、ブールベクター(bool-vectors)に細分されます。ベクターは任意の型の要素を保持できますが、文字列の要素は文字でなければならず、ブールベクターの要素はtかnilでなければなりません。文字テーブルはベクターと似ていますが、有効な文字によりインデックスづけされる点が異なります。文字列内の文字は、バッファー内の文字のようにテキストプロパティーをもつことができます(テキストのプロパティを参照)。しかしベクターはその要素が文字のときでも、テキストプロパティーをサポートしません。

リスト、文字列、およびその他の配列型も、重要な類似点を共有します。たとえば、それらはすべて長さlをもち、要素は0からl-1でインデックスづけされます。いくつかの関数はシーケンス関数と呼ばれ、これらは任意の種類のシーケンスを許容します。たとえば、関数lengthは、任意の種類のシーケンスの長さを報告します。シーケンス、配列、ベクターを参照してください。

シーケンスは読み取りにより常に新たに作成されるやめ、同じシーケンスを2回読み取るのは一般的に不可能です。シーケンスにたいする入力構文を2回読み取った場合には、内容が等しい2つのシーケンスを得ます。これには1つ例外があります。空リスト()は、常に同じオブジェクトnilを表します。

2.3.6 コンスセルとリスト型

コンスセル(cons cell)はCARスロット、CDRスロットと呼ばれる2つのスロットから構成されるオブジェクトです。それぞれのスロットはには、任意のLispオブジェクトを保持できます。そのときCARスロットに保持されるオブジェクトが何であれ、わたしたちは“このコンスセルのCAR”のような言い方をします。これはCDRの場合も同様です。

リスト(list)はコンスセルの連続するシリーズで、各コンスセルのCDRスロットは次のコンスセル、または空リストを保持します。空リストは実際にはシンボルnilです。詳細については、リストを参照してください。ほとんどのコンスセルはリストの一部として使用されるので、わたしたちはコンスセルにより構成される任意の構造を、リスト構造(list structure)という用語で参照します。

Cプログラマーにたいする注意: Lispのリストはコンスセルにより構築されるリンクリスト(linked list)として機能する。Lispではポインターは暗黙的なので、コンスセルのスロットが値を“保持(hold)”するのか、それとも値を“指す(point)”のかは区別しない。

コンスセルはLispの中核なので、コンスセルではないオブジェクトにたいする用語もあります。これらのオブジェクトはアトム(atoms)と呼ばれます。

リストにたいする入力構文とプリント表現は同じで左カッコ、任意の数の要素、右カコから構成されます。以下はリストの例です:

(A 2 "A")            ; 3要素のリスト
()                   ; 要素がないリスト(空リスト)
nil                  ; 要素がないリスト(空リスト)
("A ()")             ; 1要素のリスト: 文字列"A ()"
(A ())               ; 2要素のリスト: Aと空リスト
(A nil)              ; 同上
((A B C))            ; 1要素のリスト
                     ;   (この要素は、3要素のリスト)

読み取りではカッコの内側はリストの要素になります。つまりコンスセルは各要素から作成されます。コンスセルのCARスロットは要素を保持し、CDRスロットはリスト内の次のコンスセル(このコンスセルはリスト内の次の要素をする)を参照します。最後のコンスセルのCDRスロットはnilを保持するようにセットされます。

CARやCDRという名称はLispの歴史に由来します。オリジナルのLisp実装はIBM 704コンピューターで実行されていました。ワードを2つの部分、つまり“address”と呼ばれる部分と、“decrement”と呼ばれる部分に分割していて、その際CARはaddress部から内容を取り出す命令で、CDRはdecrement部から内容を取り出す命令でした。これとは対照的に“cons cells”は、これらを作成する関数consから命名されました。この関数は関数の目的、すなわちセルを作る(construction of cells)という目的から命名されました。

2.3.6.1 ボックスダイアグラムとしてのリストの描写

コンスセルを表現するドミノのような1対のボックスによる図で、リストを説明することができます(Lispリーダーがこのような図を読み取ることはできない。人間とコンピューターが理解できるテキスト表記と異なり、ボックス図は人間だけが理解できる)。この図は3要素のリスト(rose violet buttercup)を表したものです:

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup

この図では、ボックスは任意のLispオブジェクトへの参照を保持できるスロットを表します。ボックスのペアーはコンスセルを表します。矢印はLispオブジェクト(アトム、または他のコンスセル)への参照を表します。

この例では、1番目のボックスは1番目のコンスセルで、それのCARはrose(シンボル)を参照または保持します。2番目のボックスは1番目のコンスセルのCDRを保持し、次のボックスペアすなわち2番目のコンスセルを参照します。2番目のコンスセルのCARはvioletで、CDRは3番目のコンスセルです。(最後の)3番目のコンスセルのCDRはnilです。

同じリスト(rose violet buttercup)を、違うやり方で描いた別の図で表してみましょう:

 ---------------       ----------------       -------------------
| car   | cdr   |     | car    | cdr   |     | car       | cdr   |
| rose  |   o-------->| violet |   o-------->| buttercup |  nil  |
|       |       |     |        |       |     |           |       |
 ---------------       ----------------       -------------------

要素がないリストは空リスト(empty list)で、これはシンボルnilと同じです。言い換えるとnilはシンボルであり、かつリストでもあります。

以下はリスト(A ())、または等価な(A nil)をボックスと矢印で描いたものです:

    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> A        --> nil

以下はもっと複雑な例です。これは1番目の要素が2要素のリストであるような、3要素のリスト((pine needles) oak maple)を表します:

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
     |             --> oak      --> maple
     |
     |     --- ---      --- ---
      --> |   |   |--> |   |   |--> nil
           --- ---      --- ---
            |            |
            |            |
             --> pine     --> needles

同じリストを2番目のボックス表記で表すと、以下のようになります:

 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   o   |   o------->| oak   |   o------->| maple |  nil |
|   |   |      |     |       |      |     |       |      |
 -- | ---------       --------------       --------------
    |
    |
    |        --------------       ----------------
    |       | car   | cdr  |     | car     | cdr  |
     ------>| pine  |   o------->| needles |  nil |
            |       |      |     |         |      |
             --------------       ----------------

2.3.6.2 ドットペア表記

ドットペア表記(dotted pair notation)は、CARとCDRが明示的に表されたコンスセルの一般的な構文です。この構文では(a . b)がCARがオブジェクトa、CDRがオブジェクトbという意味になります。CDRがリストである必要がないので、ドットペア表記はより一般的なリスト構文です。しかしリスト構文が機能するような場合には、より扱いにくくなります。ドットペア表記では、リスト‘(1 2 3)’は‘(1 . (2 . (3 . nil)))’と記述されます。nilで終端されたリストにたいしては、どちらの表記法も使用できますが、リスト表記の方が通常は明解で便利です。リストをプリントする場合には、コンスセルのCDRがリストでないときだけドットペア表記が使用されます。

以下はボックスを使用してドットペア表記を表した例です。これはペア(rose . violet)を表します:

    --- ---
   |   |   |--> violet
    --- ---
     |
     |
      --> rose

最後のCDRが非nilのコンスセルのチェーンを表すので、ドットペア表記とリスト表記を組み合わせることができます。リストの最後の要素の後にドットを記述して、その後に最後のコンスセルのCDRを記述します。たとえば(rose violet . buttercup)は、(rose . (violet . buttercup))と等価です。オブジェクトは以下のようになります:

    --- ---      --- ---
   |   |   |--> |   |   |--> buttercup
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet

構文(rose . violet . buttercup)は無効です。なぜならこれは何も意味していないからです。何か意味があるとしても、violetのためにCDRがすでに使用されているコンスセルのCDRに、buttercupを置くということになります。

リスト(rose violet)は(rose . (violet))と等価であり、以下のようになります:

    --- ---      --- ---
   |   |   |--> |   |   |--> nil
    --- ---      --- ---
     |            |
     |            |
      --> rose     --> violet

同様に3要素のリスト(rose violet buttercup)は、(rose . (violet . (buttercup)))と等価です。これは以下のようになります:

    --- ---      --- ---      --- ---
   |   |   |--> |   |   |--> |   |   |--> nil
    --- ---      --- ---      --- ---
     |            |            |
     |            |            |
      --> rose     --> violet   --> buttercup

2.3.6.3 連想リスト型

連想リスト(association list)またはalistは、要素がコンスセルであるように特別に構成されたリストです。各要素においては、CARがキー(key)で、CDRが連想値(associated value)であると考えます(連想値がCDRのCARに保存される場合もある)。リストの先頭への連想値の追加と削除は簡単なので、連想リストはスタック(stack)にしばしば使用されます。

たとえば、

(setq alist-of-colors
      '((rose . red) (lily . white) (buttercup . yellow)))

これは変数alist-of-colorsに3要素のalistをセットします。最初の要素では、roseがキーでredが値になります。

alistとalist関数についての詳細な説明は連想リストを参照してください。(多くのキーの操作をより高速に行なう)テーブルを照合する他の手段についてはハッシュテーブルを参照してください。

2.3.7 配列型

配列(array)は、他のLispオブジェクトを保持または参照する任意の数のスロットから構成され、メモリーの連続ブロックに配列されます。配列の任意の要素へのアクセス時間は大体同じです。対照的にリストの要素にたいするアクセスは、リスト内でのその要素の位置に比例した時間を要します(リストの最後の要素にアクセスするにはリストの最初の要素にアクセスするより長い時間が必要)。

Emacsは文字列(strings)、ベクター(vectors)、ブールベクター(bool-vectors)、文字テーブル(char-tables)という4種の配列を定義します。

文字列は文字の配列であり、ベクターは任意のオブジェクトの配列です。ブールベクターはtかnilだけを保持できます。この種の配列は、もっとも大きい整数までの任意の長さをもつことができます。文字テーブルは、任意の有効な文字コードによりインデックスづけされる疎な配列であり、任意のオブジェクトを保持することができます。

配列の最初の要素はインデックス0、2番目の要素はインデックス1、...となります。これは0基準(zero-origin)のインデックスづけと呼ばれます。たとえば、4要素の配列はインデックス0、1、2、3をもちます。利用できる最大のインデックス値は、配列の長さより1つ小さくなります。▼一度配列が作成されると、長さは固定されます。

Emacs Lispのすべての配列は、1次元です(他のほとんどのプログラミング言語は多次元配列をサポートするが、これらは必須ではない。ネストされた1次元配列により同じ効果を得ることが可能)。各種の配列は独自の入力構文をもちます。詳細は以降のセクションを参照してください。

配列型はシーケンス型のサブセットであり文字列型、ベクター型、ブールベクター型、文字テーブル型が含まれます。

2.3.8 文字列型

文字列(string)とは文字の配列です。Emacsがテキストエディターであることから予想できるように、文字列はたとえばLispシンボルの名前、ユーザーへのメッセージ、バッファーから抽出されたテキストの表現など多くの目的のために使用されます。Lispの文字列は定数です。文字列を評価すると、それと同じ文字列がリターンされます。

文字列を操作する関数については文字列と文字を参照してください。

2.3.8.1 文字列の構文

文字列にたいする入力構文は"like this"のようにダブルクォート、任意個数の文字、もう1つのダブルクォートから構成されます。文字列内にダブルクォートを含める場合は、それの前にバックスラッシュを記述します。したがって"\""は1つのダブルクォート文字だけを含む文字列です。同様にバックスラッシュを含める場合は、"this \\ is a single embedded backslash"のように、それの前にもう1つのバックスラッシュを記述します。

文字列にたいする入力構文では、改行(newline)は特別ではありません。ダブルクォートの間に改行を記述すれば、その改行は文字列内の文字となります。しかしエスケープされた改行 — 前に‘\’をともなう改行 — は文字列の一部とはなりません。同様にエスケープされたスペース‘\ ’も無視されます。

"It is useful to include newlines
in documentation strings,
but the newline is \
ignored if escaped."
     ⇒ "It is useful to include newlines
in documentation strings,
but the newline is ignored if escaped."

2.3.8.2 文字列内の非ASCII文字

Emacdの文字列内の非ASCII文字にたいしては2つのテキスト表現 — マルチバイト(multibyte)とユニバイト(unibyte)があります(テキストの表現方法を参照)。大まかに言うとユニバイト文字列にはraw(生)バイトが保存され、マルチバイト文字列には人間が読めるテキストが保存されます。ユニバイト文字列内の各文字はバイトであり、値は0から255となります。対照的にマルチバイト文字列内の各文字は、0から4194303の値をもつかもしれません(文字型を参照)。いずれも127より上の文字は非ASCIIです。

文字をリテラルとして記述することにより、文字列に非ASCII文字を含めることができます。マルチバイトのバッファーや文字列、あるいはマルチバイトとしてvisitされたファイル等、マルチバイトのソースから文字列定数を読み込む場合、Emacsは非ASCII文字をマルチバイト文字として読み取り、その文字列を自動的にマルチバイト文字列にします。ユニバイトのソースから文字列定数を読み込む場合、Emacsは非ASCII文字をユニバイト文字として読み取り、その文字列をユニバイト文字列にします。

マルチバイト文字列内にリテラルとして文字を記述するかわりに、エスケープシーケンスを使用して文字コードとして記述できます。エスケープシーケンスについての詳細は、一般的なエスケープ構文を参照してください。

文字列定数内でUnicodeスタイルのエスケープシーケンス‘\uNNNN’または‘\U00NNNNNN’を使用する場合、(たとえASCII文字であっても)Emacsは自動的に文字列をマルチバイトとみなします。

文字列定数内で16進エスケープシーケンス(‘\xn’)と8進エスケープシーケンス(‘\n’)を使用することもできます。しかし注意してください: 文字列定数が16進または8進のエスケープシーケンスを含み、それらのエスケープシーケンスすべてがユニバイト文字(256より小)を指定していて、その文字列内に他にリテラルの非ASCII文字またはUnicodeスタイルのエスケープシーケンスが存在しない場合、Emacsは自動的に文字列をユニバイト文字列とみなします。つまり文字列内のすべての非ASCII文字は8ビットのrawバイトとみなされます。

16進および8進のエスケープシーケンスでは、エスケープされた文字コードに可変個の数字が含まれるかもしれないので、それに続く文字で16進および8進として有効ではない最初の文字は、そのエスケープシーケンスを終了させます。文字列内の次の文字が16進または8進として解釈できる文字の場合は、‘\ ’(バックスラッシュとスペース)を記述して、エスケープシーケンスを終了できます。たとえば‘\xe0\ ’はgrave accentつきの‘a’という1文字を表します。文字列内の‘\ ’はバックスラッシュ改行と同様です。これは文字列内の文字とはなりませんが、先行する16進エスケープを終了します。

2.3.8.3 文字列内の非プリント文字

リテラル文字と同様に、文字列定数内でバックスラッシュによるエスケープシーケンスを使用できます(ただし文字定数を開始するクエスチョンマークは使用しない)。たとえば非プリント文字のタブとC-aを含む文字列は、"\t, \C-a"のように、それらの間にカンマとスペースを記述します。文字にたいする入力構文については文字型を参照してください。

しかしバックスラッシュによるエスケープシーケンスとともに記述できるすべての文字が、文字列内で有効というわけではありません。文字列が保持できるコントロール文字はASCIIコントロール文字だけです。ASCIIコントロール文字では、文字列のcaseは区別されません。

正確に言うと、文字列はメタ文字を保持できません。しかし文字列がキーシーケンスとして使用される場合には、文字列内でメタ修飾されたASCII文字を表現するための方法を提供する特別な慣習があります。文字列定数内でメタ文字を示すために‘\M-’構文を使用した場合、これは文字列内の文字の 2**7 のビットをセットします。その文字列がdefine-keyまたはlookup-keyで使用される場合、この数字コードは等価なメタ文字に変換されます。文字型を参照してください。

文字列はハイパー(hyper)、スーパー(super)、アルト(alt)で修飾された文字を保持できません。

2.3.8.4 文字列内のテキストプロパティ

文字列にはその文字自身に加えて、文字のプロパティーも保持することができます。これにより特別なことをしなくても、文字列とバッファーとの間でテキストをコピーするプログラムが、テキストプロパティーをコピーすることが可能になります。テキストプロパティーが何を意味するかについてはテキストのプロパティを参照してください。テキストプロパティーをもつ文字列は、特別な入力構文とプリント構文を使用します。

#("characters" property-data...)

ここでproperty-dataは,3個でグループ化された0個以上の要素から構成されます:

beg end plist

要素begおよびendは整数で、文字列内のインデックスの範囲を指定します。plistはその範囲にたいするプロパティーリストです。たとえば、

#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))

これはテキスト内容が‘foo bar’で、最初の3文字はfaceプロパティーに値boldをもち、最後の3文字はfaceプロパティーに値italicをもつことを表します(4番目の文字にはテキストプロパティーはないので、プロパティーリストはnil。実際には範囲の中の指定されていない文字はデフォルトではプロパティーをもたないので、範囲のプロパティーリストをnilと指定する必要ない)。

2.3.9 ベクター型

ベクター(vector)は任意の型の要素からなる1次元の配列です。ベクター内の任意の要素へのアクセスに要す時間は一定です(リストの場合では要素へのアクセスに要す時間は、リストの先頭からその要素までの距離に比例する)。

ベクターのプリント表現は左角カッコ(left square bracket)、要素、右角カッコ(right square bracket)から構成されます。これは入力構文でもあります。数字や文字列と同様にベクターは評価において定数と判断されます。

[1 "two" (three)]      ; 3要素のベクター
     ⇒ [1 "two" (three)]

ベクターに作用する関数についてはベクターを参照してください。

2.3.10 文字テーブル型

文字テーブル(char-table)は任意の型の要素をもつ1次元の配列であり、文字コードによりインデックスづけされます。文字テーブルは、文字コードに情報を割り当てることを必要とする多くの処理を簡単にするための、特別な追加の機能をもちます — たとえば文字テーブルは継承する親、デフォルト値、特別な目的のために使用する余分なスロットをいくつかもつことができます。文字テーブルは文字セット全体にたいして1つの値を指定することもできます。

文字テーブルのプリント表現はベクターと似ていますが、最初に余分な‘#^’があります¹。

文字テーブルを操作する特別な関数については文字テーブルを参照してください。文字テーブルの使用には以下が含まれます:

caseテーブル(caseテーブルを参照)。
文字カテゴリーテーブル(カテゴリーを参照)。
ディスプレーテーブル(ディスプレーテーブルを参照)。
構文テーブル(構文テーブルを参照)。

2.3.11 ブールベクター型

ブールベクター(bool-vector)は、要素がtかnilのいずれかでなければならない1次元の配列です。

ブールベクターのプリント表現は文字列と似ていますが、後に長さを記述した‘#&’で始まります。これに続く文字列定数は、ビットマップとして実際に内容を指定するブールベクターです — 文字列定数内のそれぞれの“文字”は8ビットを含み、これはブールベクターの次の8要素を指定します(1はt、0はnilです)。文字の最下位ビットブールベクターの最下位のインデックスに対応します。

(make-bool-vector 3 t)
     ⇒ #&3"^G"
(make-bool-vector 3 nil)
     ⇒ #&3"^@"

‘C-g’の2進コードは111、‘C-@’はコード0の文字なのでこの結果は理にかなっています。

長さが8の倍数でなければプリント表現には余分な要素が表示されますが、これらの余分な要素に意味はありません。たとえば以下の例では、最初の3ビットだけが使用されるので2つのブールベクターは等価です:

(equal #&3"\377" #&3"\007")
     ⇒ t

2.3.12 ハッシュテーブル型

ハッシュテーブルは非常に高速な照合テーブルの一種で、キーを対応する値にマップするalistと似ていますがより高速です。ハッシュテーブルのプリント表現では、以下のようにハッシュテーブルのプロパティーと内容を指定します:

(make-hash-table)
     ⇒ #s(hash-table size 65 test eql rehash-size 1.5
                             rehash-threshold 0.8125 data ())

ハッシュテーブルについての詳細はハッシュテーブルを参照してください。

2.3.13 関数型

他のプログラミング言語の関数と同様、Lisp関数は実行可能なコードです。他の言語と異なり、Lispの関数はLispオブジェクトでもあります。Lispのコンパイルされていない関数はラムダ式 — つまり1番目の要素がシンボルlambdaであるリストです(ラムダ式を参照)。

ほとんどのプログラミング言語では名前のない関数はありません。Lispでは関数に本質的な名前はありません。名前がなくてもラムダ式を関数として呼び出すことができます。これを強調するために、わたしたちはこれを無名関数(anonymous function)とも呼びます(無名関数を参照)。Lispの名前つき関数は関数セルに有効な関数がセットされた単なるシンボルです(関数の定義を参照)。

ほとんどの場合、関数はLispプログラム内のLisp式の名前が記述されたところで呼び出されます。しかし実行時に関数オブジェクトを構築または取得してから、プリミティブ関数funcallおよびapplyにより呼び出すことができます。関数の呼び出しを参照してください。

2.3.14 マクロ型

Lispマクロ(Lisp macro)はLisp言語を拡張するユーザー定義の構成です。これはオブジェクトとしてではなく関数のように表現されますが、引数の渡し方の意味が異なります。Lispマクロの形式はリストです。これは最初の要素がmacroで、CDRがLisp関数オブジェクト(lambdaシンボルを含む)であるようなリストです。

Lispマクロオブジェクトは通常、ビルトインのdefmacro関数で定義されますが、macroで始まる任意のリストもEmacsにとってはマクロです。マクロを記述する方法の説明はマクロを参照してください。

警告: Lispマクロとキーボードマクロ(キーボードマクロを参照)は完全に別の物である。修飾なしで“マクロ”という単語を使用したときは、キーボードマクロではなくLispマクロのことを指す。

2.3.15 プリミティブ関数型

プリミティブ関数(primitive function)とは、Cプログラミング言語で記述されたLispから呼び出せる関数です。プリミティブ関数はsubrsやビルトイン関数(built-in functions)とも呼ばれます(単語“subr”は“サブルーチン(subroutine)”が由来)。ほとんどのプリミティブ関数ハ、呼び出されたときニすべての引数を評価します。すべての引数を評価しないプリミティブ関数はスペシャルフォーム(special form)と呼ばれます(スペシャルフォームを参照)。

呼び出す側からすれば、その関数がプリミティブ関数かどうかは問題になりません。しかしプリミティブ関数をLispで記述された関数で再定義した場合に問題になります。理由はそのプリミティブ関数がCコードから直接呼び出されているかもしれないからです。Lispから再定義した関数を呼び出すと新しい定義を使用するでしょうが、Cコードから呼び出すとビルトインの定義が使用されるでしょう。したがって、プリミティブ関数の再定義はしないでください。

関数(function)という用語で、LispやCで記述されたすべてのEmacs関数を参照します。Lispで記述された関数についての情報は関数型を参照してください。

プリミティブ関数に入力構文はなく、サブルーチン名とともにハッシュ表記でプリントします。

(symbol-function 'car)          ; そのシンボルの関数セルに
                                ;     アクセスする
     ⇒ #<subr car>
(subrp (symbol-function 'car))  ; これはプリミティブ関数?
     ⇒ t                ;    そのとおり

2.3.16 バイトコード関数型

バイトコード関数オブジェクト(byte-code function objects)は、Lispコードをバイトコンパイルすることにより生成されます(バイトコンパイルを参照)。バイトコード関数オブジェクトは、内部的にはベクターによく似ています。しかしバイトコード関数オブジェクトが関数呼び出しのように見える場合、評価プロセスによりこのデータ型は特別に処理されます。バイトコード関数オブジェクトを参照してください。

バイトコード関数オブジェクトのプリント表現と入力構文はベクターのものと似ていますが、開き角カッコ‘[’の前に‘#’があります。

2.3.17 Record Type

A record is much like a vector. However, the first element is used to hold its type as returned by type-of. The purpose of records is to allow programmers to create objects with new types that are not built into Emacs.

See section Records, for functions that work with records.

2.3.18 Type Descriptors

A type descriptor is a record which holds information about a type. Slot 1 in the record must be a symbol naming the type, and type-of relies on this to return the type of record objects. No other type descriptor slot is used by Emacs; they are free for use by Lisp extensions.

An example of a type descriptor is any instance of cl-structure-class.

2.3.19 autoload型

autoloadオブジェクト(autoload object)は、最初の要素がシンボルautoloadのリストです。これはシンボルの関数定義として保存され、実際の定義にたいする代替としての役割をもちます。autoloadオブジェクトは、必要な時にロードされるLispコードファイルの中で実際の定義を見つけることができることを宣言します。これにはファイル名と、それに加えて実際の定義についての他のいくつかの情報が含まれます。

ファイルのロード後、そのシンボルはautoloadオブジェクトではない新しい関数定義をもつはずです。新しい定義は、最初からそこにあったかのように呼び出されます。ユーザーの観点からは関数呼び出しは期待された動作、つまりロードされたファイル内の関数定義を使用します。

autoloadオブジェクトは通常、シンボルの関数セルにオブジェクトを保存する関数autoloadにより作成されます。詳細はautoloadを参照してください。

2.3.20 Finalizer Type

ファイナライザーオブジェクト(finalizer object)は、オブジェクトがもはや必要なくなった後のLispコードのクリーンアップを助けます。ファイナライザーは、Lisp関数オブジェクトを保持します。ガーベージコレクションのオアス後にファイナライザーオブジェクトが到達不能になったとき、Emacsはそのファイナライザーに関連付けられた関数オブジェクトを呼び出します。ファイナライザーの到達可否の判定時、もしかしてファイナライザーオブジェクト自身が参照を離さないのではないかと心配することなくファイナライザーを使用できるように、Emacsはファイナラーオブジェト自身からの参照は勘定しません。

ファイナラーザー内でのエラーは*Messages*にプリントされます。その関数が失敗しても、Emacsは与えられたファイナライザーオブジェクトに関連付けられた関数を正確に1回実行します。

Function: make-finalizer function: functionを実行するファイナライザーを作成する。functionはガーベージコレクション後、リターンされたファイナライザーオブジェクトが到達不能になったときに実行される。そのファイナライザーオブジェクトがファイナライザーオブジェクトからの参照を通じてのみ到達可能なら、functionの実行是非の判断時の目的にたいして、それは到達可能とみなされない。functionはファイナライザーオブジェクトごとに1回実行される。

2.4 編集用の型

前セクションの型は一般的なプログラミング目的のために使用され、これらの型のほとんどはLisp方言のほとんどで一般的です。Emacs Lispは編集に関する目的のために、いくつかの追加のデータ型を提供します。

2.4.1 バッファー型		編集のための基本オブジェクト。
2.4.2 マーカー型		バッファー内の位置。
2.4.3 ウィンドウ型		バッファーはウィンドウ内に表示される。
2.4.4 フレーム型		ウィンドウはフレームを細分化する。
2.4.5 端末型		フレームを表示する端末デバイス。
2.4.6 ウィンドウ構成型		フレームが細分化された方法を記録する。
2.4.7 フレーム構成型		すべてのフレームの状態を記録する。
2.4.8 プロセス型		背後のOS上で実行されるEmacsのサブプロセス。
2.4.9 Thread Type		A thread of Emacs Lisp execution.
2.4.10 Mutex Type		An exclusive lock for thread synchronization.
2.4.11 Condition Variable Type		Condition variable for thread synchronization.
2.4.12 ストリーム型		文字の受信と送信。
2.4.13 キーマップ型		どのキーストロークがどの関数を呼び出すか。
2.4.14 オーバーレイ型		オーバーレイが表示される方法。
2.4.15 フォント型		テキストを表示するフォント。

2.4.1 バッファー型

バッファー(buffer)とは、編集されるテキストを保持するオブジェクトです(バッファーを参照)。ほとんどのバッファーはディスクファイル(ファイルを参照)の内容を保持するので編集できますが、他の目的のために使用されるものもいくつかあります。ほとんどのバッファーはユーザーにより閲覧されることも意図しているので、いつかはウィンドウ内(ウィンドウを参照)に表示されます。しかしバッファーはウィンドウに表示される必要はありません。バッファーはそれぞれ、ポイント(point)と呼ばれる位置指定をもちます(ポジションを参照)。ほとんどの編集コマンドは、カレントバッファー内のポイントに隣接する内容を処理します。常に1つのバッファーがカレントバッファー(current buffer)です。

バッファーの内容は文字列によく似ていますが、バッファーはEmacs Lispの文字列と同じようには使用されず、利用可能な操作は異なります。文字列にテキストを挿入するためには部分文字列の結合が必要で、結果は完全に新しい文字列オブジェクトなのるのにたいして、バッファーでは既存のバッファーに効率的にテキストを挿入してバッファーの内容を変更できます。

標準的なEmacs関数の多くは、カレントバッファー内の文字を操作したりテストするためのものです。このマニュアルはこれらの関数の説明のために、1つのチャプターを設けています(テキストを参照)。

他のデータ構造のいくつかは、各バッファーに関連付けられています:

ローカル構文テーブル(構文テーブルを参照)。
ローカルキーマップ(キーマップを参照)。
バッファーローカルな変数バインディングのリスト(バッファーローカル変数を参照)。
オーバーレイ(オーバーレイを参照)。
バッファー内のテキストにたいするテキストプロパティー(テキストのプロパティを参照)。

ローカルキーマップと変数リストは、グローバルなバインディングや値を個別にオーバーライドするためのエントリーを含みます。これらは実際にプログラムを変更することなく、異なるバッファーでプログラムの振る舞いをカスタマイズするために使用されます。

バッファーはインダイレクト(indirect: 間接) — つまり他のバッファーとテキストを共有するがそれぞれ別に表示する — かもしれません。インダイレクトバッファーを参照してください。

バッファーに入力構文はありません。バッファーはバッファー名を含むハッシュ表記でプリントされます。

(current-buffer)
     ⇒ #<buffer objects.texi>

2.4.2 マーカー型

マーカー(marker)は特定のバッファー内の位置を表します。したがってマーカーには2つの内容 — 1つはバッファー、もう1つは位置 — をもちます。バッファーのテキストの変更では、マーカーが常にバッファー内の同じ2つの文字の間に位置することを確実にするために、必要に応じて自動的に位置の値が再配置されます。

マーカーは入力構文をもちません。マーカーはカレントの文字位置とそのバッファー名を与える、ハッシュ表記でプリントされます。

(point-marker)
     ⇒ #<marker at 10779 in objects.texi>

マーカーのテスト、作成、コピー、移動の方法についての情報はマーカーを参照してください。

2.4.3 ウィンドウ型

ウィンドウ(window)はEmacsがバッファーを表示するために使用する端末スクリーンの部分を記述します。すべてのウィンドウは関連付けられた1つのバッファーをもち、バッファーの内容はそのウィンドウに表示されます。それとは対照的に、あるバッファーは1つのウィンドウに表示されるか表示されないか、それとも複数のウィンドウに表示されるかもしれません。

同時に複数のウィンドウが存在するかもしれませんが、常に1つのウィンドウが選択されたウィンドウ(selected window)になります。Emacsがコマンドにたいして準備できているときは、(通常は)カーソルが表示されるウィンドウが選択されたウィンドウです。選択されたウィンドウは、通常はカレントバッファー(カレントバッファーを参照)を表示しますがこれは必須ではありません。

スクリーン上でウィンドウはフレームにグループ化されます。ウィンドウはそれぞれ、ただ1つのフレームだけに属します。フレーム型を参照してください。

ウィンドウは入力構文をもちません。ウィンドウはウィンドウ番号と表示されているバッファー名を与える、ハッシュ表記でプリントされます。与えられたウィンドウに表示されるバッファーは頻繁に変更されるかもしれないので、一意にウィンドウを識別するためにウィンドウ番号が存在します。

(selected-window)
     ⇒ #<window 1 on objects.texi>

ウィンドウに作用する関数の説明はウィンドウを参照してください。

2.4.4 フレーム型

フレーム(frame)とは１つ以上のEmacsウィンドウを含むスクリーン領域です。スクリーン領域を参照するためにEmacsが使用するLispオブジェクトを指す場合にも“フレーム”という用語を使用します。

フレームは入力構文をもちません。フレームはフレームのタイトルとメモリー内のアドレス(フレームを一意に識別するのに有用)を与えるハッシュ表記でプリントされます。

(selected-frame)
     ⇒ #<frame emacs@psilocin.gnu.org 0xdac80>

フレームに作用する関数の説明はフレームを参照してください。

2.4.5 端末型

端末(terminal)は1つ以上のEmacsフレーム(フレーム型を参照)を表示する能力があるデバイスです。

端末は入力構文をもちません。端末はその端末の順序番号とTTYデバイスファイル名を与える、ハッシュ表記でプリントされます。

(get-device-terminal nil)
     ⇒ #<terminal 1 on /dev/tty>

2.4.6 ウィンドウ構成型

ウィンドウ構成(window configuration)はフレーム内のウィンドウの位置とサイズ、内容についての情報を保持します。これにより後で同じウィンドウ配置を再作成できます。

ウィンドウ構成は入力構文をもちません。ウィンドウ構成のプリント表現は‘#<window-configuration>’のようになります。ウィンドウ構成に関連するいくつかの関数の説明はウィンドウの構成を参照してください。

2.4.7 フレーム構成型

フレーム構成(frame configuration)はすべてのフレーム内のウィンドウの位置とサイズ、内容についての情報を保持します。これは基本型ではありません — 実際のところ、これはCARがframe-configurationでCDRがalistであるようなリストです。それぞれのalist要素は、その要素のCARに示される1つのフレームを記述します。

フレーム構成に関連するいくつかの関数の説明はフレーム構成を参照してください。

2.4.8 プロセス型

プロセス(process)という単語は、通常は実行中のプログラムを意味します。Emacs自身はこの種のプロセス内で実行されます。しかしEmacs Lispでは、プロセスとはEmacsプロセスにより作成されたサブプロセスを表すLispオブジェクトです。シェル、GDB、ftp、コンパイラーなどのプログラムは、Emacsのサブプロセスとして実行されEmacsの能力を拡張します。さらに操作を行なうために、EmacsサブプロセスはEmacsからテキスト入力を受け取り、テキスト出力をEmacsにリターンします。Emacsがサブプロセスにシグナルを送ることもできます。

プロセスオブジェクトは入力構文をもちません。プロセスオブジェクトはプロセス名を与えるハッシュ表記でプリントされます。

(process-list)
     ⇒ (#<process shell>)

プロセスの作成、削除、プロセスに関する情報のリターン、入力やシグナルの送信、出力の受信を行なう関数についての情報はプロセスを参照してください。

2.4.9 Thread Type

A thread in Emacs represents a separate thread of Emacs Lisp execution. It runs its own Lisp program, has its own current buffer, and can have subprocesses locked to it, i.e. subprocesses whose output only this thread can accept. See section Threads.

Thread objects have no read syntax. They print in hash notation, giving the name of the thread (if it has been given a name) or its address in core:

(all-threads)
    ⇒ (#<thread 0176fc40>)

2.4.10 Mutex Type

A mutex is an exclusive lock that threads can own and disown, in order to synchronize between them. See section Mutexes.

Mutex objects have no read syntax. They print in hash notation, giving the name of the mutex (if it has been given a name) or its address in core:

(make-mutex "my-mutex")
    ⇒ #<mutex my-mutex>
(make-mutex)
    ⇒ #<mutex 01c7e4e0>

2.4.11 Condition Variable Type

A condition variable is a device for a more complex thread synchronization than the one supported by a mutex. A thread can wait on a condition variable, to be woken up when some other thread notifies the condition.

Condition variable objects have no read syntax. They print in hash notation, giving the name of the condition variable (if it has been given a name) or its address in core:

(make-condition-variable (make-mutex))
    ⇒ #<condvar 01c45ae8>

2.4.12 ストリーム型

ストリーム(stream)とは、文字のソースまたはシンクとして — つまり入力として文字を供給したり、出力として文字を受け入れるために使用できるオブジェクトです。多くの異なるタイプ — マーカー、バッファー、文字列、関数をこの方法で使用できます。ほとんどの場合、入力ストリーム(文字列ソース)はキーボード、バッファー、ファイルから文字を受け取り、出力ストリーム(文字シンク)は文字を*Help*バッファーのようなバッファーやエコーエリアに文字を送ります。

オブジェクトnilは、他の意味に加えてストリームとして使用されることがあります。nilは変数standard-inputやstandard-outputの値を表します。オブジェクトtも入力としてミニバッファー(ミニバッファーを参照)、出力としてエコーエリア(エコーエリアを参照)の使用を指定するストリームになります。

ストリームは特別なプリント表現や入力構文をもたず、それが何であれそれらの基本型としてプリントされます。

パース関数およびプリント関数を含む、ストリームに関連した関数の説明はLispオブジェクトの読み取りとプリントを参照してください。

2.4.13 キーマップ型

キーマップ(keymap)はユーザーがタイプした文字をコマンドにマップします。このマップはユーザーのコマンド入力が実行される方法を制御します。キーマップは、実際にはCARがシンボルkeymapであるようなリストです。

キーマップの作成、プレフィクスキーの処理、ローカルキーマップやグローバルキーマップ、キーバインドの変更についての情報はキーマップを参照してください。

2.4.14 オーバーレイ型

オーバーレイ(overlay)はバッファーの一部に適用するプロパティーを指定します。それぞれのオーバーレイはバッファーの指定された範囲に適用され、プロパティーリスト(プロパティー名と値が交互に記述された要素のリスト)を含みます。オーバーレイプロパティーは、バッファーの指定された一部を、一時的に異なるスタイルで表示するために使用されます。オーバーレイは入力構文をもたず、バッファー名と範囲の位置を与えるハッシュ表記でプリントされます。

オーバーレイを作成したり使用する方法についての情報はオーバーレイを参照してください。

2.4.15 フォント型

fontはグラフィカルな端末上のテキストを表示する方法を指定します。実際には異なる3つのフォント型 — フォントオブジェクト(font objects)、フォントスペック(font specs)、フォントエンティティー(font entities) — が存在します。これらは入力構文をもちません。これらのプリント構文は‘#<font-object>’、‘#<font-spec>’、‘#<font-entity>’のようになります。これらのLispオブジェクトの説明は低レベルのフォント表現を参照してください。

2.5 循環オブジェクトの読み取り構文

複雑なLispオブジェクトでの共有された構造や循環する構造を表すために、リーダー構成‘#n=’と‘#n#’を使用することができます。

後でオブジェクトを参照するには、オブジェクトの前で#n=を使用します。その後で、他の場所にある同じオブジェクトを参照するために、#n#を使用することができます。ここでnは任意の整数です。たとえば以下は、1番目の要素が3番目の要素にも繰り替えされるリストを作成する方法です:

(#1=(a) b #1#)

これは、以下のような通常の構文とは異なります

((a) b (a))

これは1番目の要素と3番目の要素がそっくりなリストですが、これらは同じLispオブジェクトではありません。以下で違いを見ることができます:

(prog1 nil
  (setq x '(#1=(a) b #1#)))
(eq (nth 0 x) (nth 2 x))
     ⇒ t
(setq x '((a) b (a)))
(eq (nth 0 x) (nth 2 x))
     ⇒ nil

“要素”として自身を含むような循環する構造を作成するために、同じ構文を使用できます。以下は例です:

#1=(a #1#)

これは2番目の要素がそのリスト自身であるリストを作成します。これが実際にうまくいくのか、以下で確認できます:

(prog1 nil
  (setq x '#1=(a #1#)))
(eq x (cadr x))
     ⇒ t

変数print-circleを非nil値にバインドした場合、Lispプリンターは、循環および共有されるLispオブジェクトを記録するこの構文を生成することができます。出力に影響する変数を参照してください。

2.6 型のための述語

関数が呼び出されたとき、Emacs Lispインタープリター自身はその関数に渡された実際の引数の型チェックは行ないません。それが行なえないのは、Lispにおける関数の引数は他のプログラミング言語のようなデータ型宣言をもたないからです。したがって実際の引数が、その関数が使用できる型に属するかどうかをテストするのは、それぞれの関数に任されています。

すべてのビルトイン関数は適切なときに実際の引数の型チェックを行い、引数の型が違う場合はwrong-type-argumentエラーをシグナルします。たとえば以下は、+の引数に+が扱うことができない引数を渡したとき何が起こるかの例です:

(+ 2 'a)
     error→ Wrong type argument: number-or-marker-p, a

異なる型にたいして異なる処理をプログラムに行なわせる場合は、明示的に型チェックを行なわなければなりません。オブジェクトの型をチェックするもっとも一般的な方法は型述語(type predicate)関数の呼び出しです。Emacsはそれぞれの型にたいする型述語をもち、組み合わされた型にたいする述語もあります。

型述語関数は1つの引数をとり、その引数が適切な型であればt、そうでなければnilをリターンします。述語関数にたいする一般的なLisp慣習にしたがい、ほとんどの型述語の名前は‘p’で終わります。

以下はリストにたいしてチェックを行なう述語listpと、シンボルにたいしてチェックを行なう述語symbolpの例です。

(defun add-on (x)
  (cond ((symbolp x)
         ;; XがシンボルならLISTにputする
         (setq list (cons x list)))
        ((listp x)
         ;; Xがリストならその要素をLISTに追加
         (setq list (append x list)))
        (t
         ;; シンボルとリストだけを処理する
         (error "Invalid argument %s in add-on" x))))

以下のテーブルは事前定義された型述語(アルファベット順)と、さらに情報を得るためのリファレンスです。

atom: atomを参照のこと。
arrayp: arraypを参照のこと。
bool-vector-p: bool-vector-pを参照のこと。
booleanp: booleanpを参照のこと。
bufferp: bufferpを参照のこと。
byte-code-function-p: byte-code-function-pを参照のこと。
case-table-p: case-table-pを参照のこと。
char-or-string-p: char-or-string-pを参照のこと。
char-table-p: char-table-pを参照のこと。
commandp: commandpを参照のこと。
condition-variable-p: See section condition-variable-p.
consp: conspを参照のこと。
custom-variable-p: custom-variable-pを参照のこと。
floatp: floatpを参照のこと。
fontp: 低レベルのフォント表現を参照のこと。
frame-configuration-p: frame-configuration-pを参照のこと。
frame-live-p: frame-live-pを参照のこと。
framep: framepを参照のこと。
functionp: functionpを参照のこと。
hash-table-p: hash-table-pを参照のこと。
integer-or-marker-p: integer-or-marker-pを参照のこと。
integerp: integerpを参照のこと。
keymapp: keymappを参照のこと。
keywordp: 変更不可な変数を参照のこと。
listp: listpを参照のこと。
markerp: markerpを参照のこと。
mutexp: See section mutexp.
nlistp: nlistpを参照のこと。
number-or-marker-p: number-or-marker-pを参照のこと。
numberp: numberpを参照のこと。
overlayp: overlaypを参照のこと。
processp: processpを参照のこと。
recordp: See section recordp.
sequencep: sequencepを参照のこと。
string-or-null-p: string-or-null-pを参照のこと。
stringp: stringpを参照のこと。
subrp: subrpを参照のこと。
symbolp: symbolpを参照のこと。
syntax-table-p: syntax-table-pを参照のこと。
threadp: See section threadp.
vectorp: vectorpを参照のこと。
wholenump: wholenumpを参照のこと。
window-configuration-p: window-configuration-pを参照のこと。
window-live-p: window-live-pを参照のこと。
windowp: windowpを参照のこと。

あるオブジェクトがどの型かチェックするもっとも一般的な方法は、関数type-ofの呼び出しです。オブジェクトは、ただ1つだけの基本型に属することを思い出してください。type-ofは、それがどの型かを告げます(Lispのデータ型を参照)。しかしtype-ofは基本型以外の型については何も知りません。ほとんどの場合では、type-ofより型述語を使用するほうが便利でしょう。

Function: type-of object

This function returns a symbol naming the primitive type of object. The value is one of the symbols bool-vector, buffer, char-table, compiled-function, condition-variable, cons, finalizer, float, font-entity, font-object, font-spec, frame, hash-table, integer, marker, mutex, overlay, process, string, subr, symbol, thread, vector, window, or window-configuration. However, if object is a record, the type specified by its first slot is returned; Records.

(type-of 1)
     ⇒ integer

(type-of 'nil)
     ⇒ symbol
(type-of '())    ; () is nil.
     ⇒ symbol
(type-of '(x))
     ⇒ cons
(type-of (record 'foo))
     ⇒ foo

2.7 同等性のための述語

ここでは2つのオブジェクトの同一性をテストする関数を説明します。(たとえば文字列などの)特定の型のオブジェクト同士で内容の同一性をテストするのは、別の関数を使用します。これらの述語にたいしては、そのデータ型を説明する適切なチャプターを参照してください。

Function: eq object1 object2

この関数はobject1とobject2が同じオブジェクトならt、それ以外はnilをリターンする。

object1とobject2が同じ値をもつ整数なら、これらは同じオブジェクトと判断される(eqはtをリターンする)。object1とobject2が同じ名前のシンボルなら、通常は同じオブジェクトであるが例外もある。シンボルの作成とinternを参照のこと。(リストやベクター、文字列などの)他の型にたいしては、同じ内容(または要素)の2つの引数が両者eqである必要はない。これらが同じオブジェクトの場合だけeqであり、その場合は一方の内容を変更するともう一方の内容にも同じ変更が反映される。

(eq 'foo 'foo)
     ⇒ t

(eq 456 456)
     ⇒ t

(eq "asdf" "asdf")
     ⇒ nil

(eq "" "")
     ⇒ t
;; この例外は省スペースのためにEmacs Lispが
;; マルチバイトの空文字列を1つだけ作成するため

(eq '(1 (2 (3))) '(1 (2 (3))))
     ⇒ nil

(setq foo '(1 (2 (3))))
     ⇒ (1 (2 (3)))
(eq foo foo)
     ⇒ t
(eq foo '(1 (2 (3))))
     ⇒ nil

(eq [(1 2) 3] [(1 2) 3])
     ⇒ nil

(eq (point-marker) (point-marker))
     ⇒ nil

make-symbol関数はinternされていないシンボルをリターンする。これはLisp式内でその名前を記述したシンボルとは区別される。同じ名前の異なるシンボルはeqではない。シンボルの作成とinternを参照のこと。

(eq (make-symbol "foo") 'foo)
     ⇒ nil

Function: equal object1 object2

この関数はobject1とobject2が同じ構成要素をもつならt、それ以外はnilをリターンする。eqが引数が同じオブジェクトなのかテストするのにたいして、equalは同一でない引数の内部を調べて、それらの要素または内容が同一化をテストする。したがって2つのオブジェクトがeqならばそれらはequalだが、その逆は常に真ではない。

(equal 'foo 'foo)
     ⇒ t

(equal 456 456)
     ⇒ t

(equal "asdf" "asdf")
     ⇒ t

(eq "asdf" "asdf")
     ⇒ nil

(equal '(1 (2 (3))) '(1 (2 (3))))
     ⇒ t

(eq '(1 (2 (3))) '(1 (2 (3))))
     ⇒ nil

(equal [(1 2) 3] [(1 2) 3])
     ⇒ t

(eq [(1 2) 3] [(1 2) 3])
     ⇒ nil

(equal (point-marker) (point-marker))
     ⇒ t

(eq (point-marker) (point-marker))
     ⇒ nil

Comparison of strings is case-sensitive, but does not take account of text properties—it compares only the characters in the strings. See section テキストのプロパティ. Use equal-including-properties to also compare text properties. For technical reasons, a unibyte string and a multibyte string are equal if and only if they contain the same sequence of character codes and all these codes are in the range 0 through 127 (ASCII).

(equal "asdf" "ASDF")
     ⇒ nil

しかし2つの別のバッファーは、それらのテキスト内容が同じでもequalと判断されることはない。

equalのテストは再帰的に実装されています。たとえば2つのコンスセルxとyを与えると、(equal x y)は、以下の式の両方がtをリターンする場合だけtをリターンします:

(equal (car x) (car y))
(equal (cdr x) (cdr y))

これは再帰処理なので循環するリストがあると無限再帰となる(エラーとなる)。

Function: equal-including-properties object1 object2

この関数はすべてのケースにおいてequalと同様に振る舞うが、2つの文字列がequalになるためには、それらが同じテキストプロパティーをもつ必要がある。

(equal "asdf" (propertize "asdf" 'asdf t))
     ⇒ t

(equal-including-properties "asdf"
                            (propertize "asdf" 'asdf t))
     ⇒ nil

3 数値

GNU Emacsは2つの数値データ型 — 整数(integers)と浮動小数点数(floating-point numbers)をサポートします。整数は-3、0、7、13、511などの整数です。浮動小数点数は-4.5、0.0、2.71828などの小数部をもちます。これらは指数記数法でも表現できます — ‘1.5e2’は‘150.0’と同じです。ここで‘e2’は10の2乗を表し、それに1.5を乗じるという意味です。整数計算はオーバーフローするときもありますが正確です。浮動小数点数の計算にでは、数値は固定された精度をもつので、しばしば丸め誤差(rounding errors)が発生します。

3.1 整数の基礎		整数の表現と範囲。
3.2 浮動小数点数の基礎		浮動少数の表現と範囲。
3.3 数値のための述語		数にたいするテスト。
3.4 数値の比較		同一性と非同一性の述語。
3.5 数値の変換		浮動小数点数から整数の変換と逆変換。
3.6 算術演算		加減乗除の方法。
3.7 丸め処理		浮動小数点数の明示的な丸め。
3.8 ビット演算 on Integers		論理的なand、or、not、shift。
3.9 標準的な数学関数		三角関数、指数、対数関数。
3.10 乱数		予測可能または不可能な乱数の取得。

3.1 整数の基礎

整数の値の範囲はマシンに依存します。最小の範囲は-536,870,912から536,870,911(30ビット長の -2**29 から 2**29 - 1) ですが、多くのマシンはこれより広い範囲を提供します。このチャプターの例の多くは、最小の整数が30ビット長であると仮定します。

Lispリーダーは、数字のシーケンス(オプションで最初の符号記号と最後のピリオドをともなう)として整数を読み取ります。Emacsの範囲を超える整数は浮動小数点数として扱われます。

 1               ; 整数1
 1.              ; 整数1
+1               ; これも整数1
-1               ; 整数-1
 9000000000000000000
                 ; 浮動小数点数9e18
 0               ; 整数0
-0               ; 整数0

基数が10以外の整数の構文では‘#’の後に基数を指定する文字 — 2進は‘b’、8進は‘o’、16進は‘x’、‘radixr’は基数radix — を記述します。基数を指定する文字のcaseは区別されません。したがって‘#binteger’はintegerを2進として読み取り、‘#radixrinteger’はintegerを基数radixとして読み取ります。radixに指定できる値は2から36です。たとえば:

#b101100 ⇒ 44
#o54 ⇒ 44
#x2c ⇒ 44
#24r1k ⇒ 44

整数にたいして処理を行なうさまざまな関数、特にビット演算(ビット演算 on Integersを参照)を理解するためには、数を2進形式で見ることが助けになることがよくあります。

30ビットの2進では10進数の整数5は以下のようになります:

0000...000101 (全部で30ビット)

(‘...’は30ビットのワードを満たすのに充分なビットを意味しており、この場合の‘...’は12個の0ビットを意味する。以下の例でも2進の整数を読みやすくするために、‘...’の表記を使用している。)

整数の-1は以下のようになります:

1111...111111 (全部で30ビット)

-1は30個の1で表現されます(2の補数表記と呼ばれる)。

-1から4を減じることで負の整数-5が得られます。10進の整数4は2進では100です。したがって-5は以下のようになります:

1111...111011 (全部で30ビット)

この実装では、0ビットの2進の最大は10進の536,870,911です。これは2進では以下のようになります:

0111...111111 (全部で30ビット)

算術関数は整数が範囲外かどうかをチェックしないので、536,870,911に1を加えるとその値は負の整数-536,870,912になります:

(+ 1 536870911)
     ⇒ -536870912
     ⇒ 1000...000000 (全部で30ビット)

このチャプターで説明する多くの関数は、数字の位置として引数にマーカー(マーカーを参照)を受け取ります。そのような関数にたいする実際の引数は数字かマーカーなので、わたしたちはこれらの引数にnumber-or-markerという名前を与えることがあります。引数の値がマーカーならマーカーの位置が使用され、マーカーのバッファーは無視されます。

Variable: most-positive-fixnum: この変数の値はEmacs Lispが扱える整数の最大値。典型的な値は32ビットでは 2**29 - 1 、64ビットでは 2**61 - 1 。

Variable: most-negative-fixnum: この変数の値はEmacs Lispが扱える最小の整数。これは負の整数になる。典型的な値は32ビットでは -2**29 、64ビットでは -2**61、。

Emacs Lispでは、テキスト文字は整数により表現されます。0から(max-char)までの整数は、有効な文字として判断されます。文字コードを参照してください。

3.2 浮動小数点数の基礎

浮動小数点数は整数ではない数を表現するのに有用です。浮動小数点数の範囲は、使用しているマシンでのCデータ型のdoubleと同じ範囲です。Emacsで現在サポートされているすべてのコンピューターでは、これは倍精度のIEEE浮動小数点数です。

浮動小数点数にたいする入力構文は、小数点と指数のどちらか1つ、または両方が必要とします。オプションの符号(‘+’か‘-’)は、その数字と指数の前に記述します。たとえば‘1500.0’、‘+15e2’、‘15.0e+2’、‘+1500000e-3’、‘.15e4’は値が1500の浮動小数点数を記述する5つの方法です。これらはすべて等価です。Common Lispと同様、Emacs Lispは浮動小数点数の小数点の後に少なくとも1つの数字を必要とします。‘1500.’は整数であって浮動小数点数ではありません。

Emacs Lispはequalと=に関して、-0.0を通常の0と数学的に同じものとして扱います。これは、(他の処理がこれらを区別にしても-0.0と0.0は数学的に等しいとする)IEEE浮動小数点数規格にしたがっています。

IEEE浮動小数点数規格は浮動小数点数として、正の無限大と負の無限大をサポートします。この規格はNaNまたは“not a number(数字ではない)”と呼ばれる値クラスも提供します。正しい答えが存在しないような場合に、数学関数はこのような値をリターンします。たとえば(/ 0.0 0.0)はNaNをリターンします。実用に際し、たとえNaN値に符号がついていたとしても、Emacs Lispでは異なるNaN値に有意な差はありません。

以下は、これらの特別な浮動小数点数にたいする入力構文です:

infinity: ‘1.0e+INF’と‘-1.0e+INF’
not-a-number: ‘0.0e+NaN’と‘-0.0e+NaN’

以下の関数は浮動小数点数を扱うために特化したものです:

Function: isnan x: この述語は浮動小数引数がNaNならt、それ以外はnilをリターンする。

Function: frexp x

この関数はコンスセル(s . e)をリターンする。ここでsとeは、浮動小数点数の仮数(浮動小数点数を2の指数表現したときの仮数)と指数である。

xが有限ならsは0.5以上1.0未満の浮動小数点数、eは整数で、 x = s * 2**eとなる。 xが0または無限ならsはxと等しくなる。xがNaNならsもNaN。xが0ならeは0。

Function: ldexp s e: 数値の仮数sと整数の指数eを与えられると、この関数は浮動小数点数 s * 2**eをリターンする。

Function: copysign x1 x2: この関数はx2の符号をx1の値にコピーして結果をリターンする。x1とx2は浮動小数でなければならない。

Function: logb x

この関数はxの2進指数をリターンする。より正確には、これは|x|の2を底とする対数を整数に切り下げた値。

(logb 10)
     ⇒ 3
(logb 10.0e20)
     ⇒ 69

3.3 数値のための述語

このセクションの関数は数値や、特定の数値型にたいしてテストを行ないます。関数integerpとfloatpは、引数として任意のLispオブジェクト型をとることができます(でなければ、あまり使用する機会ない)。しかし述語zeropは引数として数値を要求します。マーカーのための述語のinteger-or-marker-p、number-or-marker-pも参照してください。

Function: floatp object: この述語は引数が浮動小数かどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: integerp object: この述語は引数が整数かどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: numberp object: この述語は引数が数(整数か浮動小数)かどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: natnump object

この述語は引数が正の整数かどうかをテストしてもしそうならt、それ以外はnilをリターンする(名前は“natural numberl: 自然数”が由来)。0は整数と判断される。

wholenumpはnatnumpのシノニム。

Function: zerop number

この述語は引数が0かどうかをテストしてもしそうならt、それ以外はnilをリターンする。引数は数でなければならない。

(zerop x)は(= x 0)と等価。

3.4 数値の比較

数が数値的に等しいかのテストには、eqではなく通常は=を使用するべきです。同じ数値をもつ多くの浮動小数オブジェクトが存在するかもしれません。これらを比較するのにeqを使用する場合、これは2つの値が同じオブジェクトかどうかをテストすることになります。対照的に=はオブジェクトの数値的な値だけを比較します。

Emacs Lispでは、それぞれの整数は一意なLispオブジェクトです。したがって整数に関してはeqは=と同じです。未知の整数の値の比較に、eqを使用する方が便利な場合があります。なぜなら未知の値が数でない場合でもeqはエラーを報告しないからです。対照的に引数が数でもマーカーでもない場合、=はエラーをシグナルします。しかし整数の比較においてさえ、使用できる場合は=を使用するのがよいプログラミング習慣です。

数の比較において、2つの数が同じデータ型(どちらも整数か浮動小数)では、同じ値の場合は等しい数として扱うequalのほうが便利なときもあります。対照的に=は整数と浮動小数点数を等しい数と扱うことができます。同等性のための述語を参照してください。

他の欠点もあります。浮動小数演算は正確ではないので、浮動小数値を比較するのが悪いアイデアとなるときがよくあります。通常は近似的に等しいことをテストするほうがよいでしょう。以下はこれを行なう関数です:

(defvar fuzz-factor 1.0e-6)
(defun approx-equal (x y)
  (or (= x y)
      (< (/ (abs (- x y))
            (max (abs x) (abs y)))
         fuzz-factor)))

Common Lispに関する注意: Common Lispは複数ワード整数を実装していて、2つの別の整数オブジェクトが同じ数値的な値をもつことができるので、Common Lispでの数の比較はには常に=が要求されます。Emacs Lispの整数は範囲が制限されているため、与えられた値に対応する整数オブジェクトは1つだけです。

Function: = number-or-marker &rest number-or-markers: この関数はすべての引数が数値的に等しいかどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: eql value1 value2: この関数はeqと同様に振る舞うが引数が両方とも数のときを除く。これは数を型と数値的な値により比較するので、(eql 1.0 1)はnilをリターンするが、(eql 1.0 1.0)と(eql 1 1)はtをリターンする。

Function: /= number-or-marker1 number-or-marker2: この関数は引数が数値的に等しいかどうかをテストして、もし異なる場合はt、等しい場合はnilをリターンする。

Function: < number-or-marker &rest number-or-markers: この関数は、各引数それぞれを後の引数より小さいかどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: <= number-or-marker &rest number-or-markers: この関数は、各引数それぞれが後の引数以下かどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: > number-or-marker &rest number-or-markers: この関数は、各引数それぞれが後の引数より大きいかどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: >= number-or-marker &rest number-or-markers: この関数は、各引数それぞれが後の引数以上かどうかをテストしてもしそうならt、それ以外はnilをリターンする。

Function: max number-or-marker &rest numbers-or-markers

This function returns the largest of its arguments.

(max 20)
     ⇒ 20
(max 1 2.5)
     ⇒ 2.5
(max 1 3 2.5)
     ⇒ 3

Function: min number-or-marker &rest numbers-or-markers

This function returns the smallest of its arguments.

(min -4 1)
     ⇒ -4

Function: abs number: この関数はnumberの絶対値をリターンする。

3.5 数値の変換

整数を浮動少数の変換には関数floatを使用します。

Function: float number: これは浮動小数点数に変換されたnumberをリターンする。すでにnumberが浮動小数点数ならfloatはそれを変更せずにリターンする。

浮動小数点数を整数に変換する関数が4つあります。これらは浮動小数点数を丸める方法が異なります。これらはすべて引数number、およびオプション引数としてdivisorを受け取ります。引数は両方とも整数か浮動小数点数です。divisorがnilのこともあります。divisorがnilまたは省略された場合、これらの関数はnumberを整数に変換するか、それが既に整数の場合は変更せずにリターンします。divisorが非nilなら、これらの関数はnumberをdivisorで除して結果を整数に変換します。divisorが(整数か浮動小数かに関わらず)0の場合、Emacsはarith-errorエラーをシグナルします。

Function: truncate number &optional divisor

これは0に向かって丸めることにより整数に変換したnumberをリターンする。

(truncate 1.2)
     ⇒ 1
(truncate 1.7)
     ⇒ 1
(truncate -1.2)
     ⇒ -1
(truncate -1.7)
     ⇒ -1

Function: floor number &optional divisor

これは下方(負の無限大に向かって)に丸めることにより整数に変換したnumberをリターンする。

divisorが指定された場合には、modに相当する種類の除算演算を使用して下方に丸めを行う。

(floor 1.2)
     ⇒ 1
(floor 1.7)
     ⇒ 1
(floor -1.2)
     ⇒ -2
(floor -1.7)
     ⇒ -2
(floor 5.99 3)
     ⇒ 1

Function: ceiling number &optional divisor

これは上方(正の無限大に向かって)に丸めることにより整数に変換したnumberをリターンする。

(ceiling 1.2)
     ⇒ 2
(ceiling 1.7)
     ⇒ 2
(ceiling -1.2)
     ⇒ -1
(ceiling -1.7)
     ⇒ -1

Function: round number &optional divisor

これはもっとも近い整数に向かって丸めることにより、整数に変換したnumberをリターンする。2つの整数から等距離にある値の丸めでは、偶数の整数をリターンする。

(round 1.2)
     ⇒ 1
(round 1.7)
     ⇒ 2
(round -1.2)
     ⇒ -1
(round -1.7)
     ⇒ -2

3.6 算術演算

Emacs Lispは伝統的な4つの算術演算(加減乗除)、同様に剰余とmodulusの関数、および1の加算と減算を行う関数を提供します。%を除き、これらの各関数は引き数として整数か浮動小数を受け取り、浮動小数の引数がある場合は浮動小数点数をリターンします。

Emacs Lispの算術関数は整数のオーバーフローをチェックしません。したがって(1+ 536870911)は-536870912に評価されるかもしれず、それはハードウェアーに依存します。

Function: 1+ number-or-marker

この関数はnumber-or-marker + 1をリターンする。例えば、

(setq foo 4)
     ⇒ 4
(1+ foo)
     ⇒ 5

この関数はCの演算子++とは異なり、変数をインクリメントしない。この関数は和を計算するだけである。したがって以下を続けて評価すると、

foo
     ⇒ 4

変数をインクリメントしたい場合は、以下のようにsetqを使用しなければならない:

(setq foo (1+ foo))
     ⇒ 5

Function: 1- number-or-marker: この関数はnumber-or-marker - 1をリターンする。

Function: + &rest numbers-or-markers

この関数は引数すべてを加算する。引数を与えないと+は0をリターンする。

(+)
     ⇒ 0
(+ 1)
     ⇒ 1
(+ 1 2 3 4)
     ⇒ 10

Function: - &optional number-or-marker &rest more-numbers-or-markers

-関数は2つの目的 — 符号反転と減算 — をもつ。-に1つの引数を与えると、値は引数の符号を反転したものになる。複数の引数の場合は、number-or-markerからmore-numbers-or-markersまでの各値を蓄積的に減算する。引数がなければ結果は0。

(- 10 1 2 3 4)
     ⇒ 0
(- 10)
     ⇒ -10
(-)
     ⇒ 0

Function: * &rest numbers-or-markers

この関数はすべての引数を乗じて積をリターンする。引数がなかれば*は1をリターンする。

(*)
     ⇒ 1
(* 1)
     ⇒ 1
(* 1 2 3 4)
     ⇒ 24

Function: / number &rest divisors

divisorsが1つ以上ならこの関数はdivisors内の除数で順にnumberを除して、その商をリターンする。divisorsがなければ、この関数は1/number、つまりnumberの逆数をリターンする。各引数には数かマーカーを指定できる。

すべての引数が整数なら、結果は各除算の後に商を0へ向かって丸めることにより得られる整数となる。

(/ 6 2)
     ⇒ 3

(/ 5 2)
     ⇒ 2

(/ 5.0 2)
     ⇒ 2.5

(/ 5 2.0)
     ⇒ 2.5

(/ 5.0 2.0)
     ⇒ 2.5

(/ 4.0)
     ⇒ 0.25

(/ 4)
     ⇒ 0

(/ 25 3 2)
     ⇒ 4

(/ -17 6)
     ⇒ -2

整数を整数0で除するとEmacsはarith-errorエラー(エラーを参照)をシグナルする。浮動小数点数の除算では、非0の数を0で除することで正の無限大または負の無限大を得る(浮動小数点数の基礎を参照)。

Function: % dividend divisor

この関数はdividendをdivisorで除した後、その剰余を整数でリターンする。引数は整数かマーカーでなければならない。

任意の2つの整数dividendとdivisorにたいして、

(+ (% dividend divisor)
   (* (/ dividend divisor) divisor))

は、divisorが非0なら常にdividendと等しくなる。

(% 9 4)
     ⇒ 1
(% -9 4)
     ⇒ -1
(% 9 -4)
     ⇒ 1
(% -9 -4)
     ⇒ -1

Function: mod dividend divisor

この関数はdividendのdivisorにたいするmodulo、言い換えるとdividendをdivisorで除した後の剰余(ただし符号はdivisorと同じ)をリターンする。引数は数かマーカーでなければならない。

%とは異なりmodは浮動小数の引数を許す。これは商を整数に下方(負の無限大に向かって)へ丸めて剰余を計算するのにこの商を使用する。

modはdivisorが0のとき、両方の引数が整数ならarith-errorエラーをシグナルし、それ以外はNaNをリターンする。

(mod 9 4)
     ⇒ 1

(mod -9 4)
     ⇒ 3

(mod 9 -4)
     ⇒ -3

(mod -9 -4)
     ⇒ -1

(mod 5.5 2.5)
     ⇒ .5

任意の2つの数dividendとdivisorにたいして、

(+ (mod dividend divisor)
   (* (floor dividend divisor) divisor))

は常にdividendになる(ただし引数のどちらかが浮動小数なら、丸め誤差の範囲内で等しく、かつdividendが整数でdivisorが0ならarith-errorとなる)。floorについては、数値の変換を参照のこと。

3.7 丸め処理

関数ffloor、fceiling、fround、ftruncateは浮動小数の引数をとり、値が近くの整数であるような浮動少数をリターンします。ffloorは一番近い下方の整数、fceilingは一番近い上方の整数、ftruncateは0に向かう方向で一番近い整数、froundは一番近い整数をリターンします。

Function: ffloor float: この関数はfloatを次に小さい整数値に丸めて、その値を浮動小数点数としてリターンする。

Function: fceiling float: この関数はfloatを次に大きい整数値に丸めて、その値を浮動小数点数としてリターンする。

Function: ftruncate float: この関数はfloatを0方向の整数値に丸めて、その値を浮動小数点数としてリターンする。

Function: fround float: この関数はfloatを一番近い整数値に丸めて、その値を浮動小数点数としてリターンする。2つの整数値との距離が等しい値にたいする丸めでは、偶数の整数をリターンする。

3.8 ビット演算 on Integers

コンピューターの中では、整数はビット(bit: 0か1の数字)のシーケンスである2進数で表されます。ビット演算は、そのようなシーケンスの中の個々のビットに作用します。たとえばシフト(shifting)はシーケンス全体を1つ以上左または右に移動して、移動されたのと同じパターンを再現します。

Emacs Lispのビット演算は整数だけに適用されます。

Function: lsh integer1 count

lshはlogical shiftの略で、integer1のビットを左にcount個シフトする。countが負なら右にシフトし、シフトにより空きになったビットには0がセットされる。countが負ならlshは左端(最上位)に0をシフトするので、integer1が負の場合でも正の結果が生成される。これと対照的なのが以下で説明するashである。

以下はlshでビットパターンの位置を1つ左にシフトする例である。ここでは下位8ビットの2進パターンだけを表示しており、残りのビットはすべて0である。

(lsh 5 1)
     ⇒ 10
;; 10進の5が10進の10になる
00000101 ⇒ 00001010

(lsh 7 1)
     ⇒ 14
;; 10進の7は10進の14になる
00000111 ⇒ 00001110

この例が示すように、ビットパターンを左に1シフトすると、生成される数は元の数の2倍になる。

ビットパターンを左に2シフトすると、以下の結果が生成される(8ビット2進数):

(lsh 3 2)
     ⇒ 12
;; 10進の3が10進の12になる
00000011 ⇒ 00001100

一方、右に1シフトすると以下のようになる:

(lsh 6 -1)
     ⇒ 3
;; 10進の6は10進の3になる
00000110 ⇒ 00000011

(lsh 5 -1)
     ⇒ 2
;; 10進の5は10進の2になる
00000101 ⇒ 00000010

例で明らかなように右に1シフトすることにより、正の整数の値が2で除され下方に丸められる。

関数lshは他のEmacs Lisp算術関数と同様、オーバーフローをチェックしないので、左にシフトすることにより上位ビットが捨てられ、その数の符号が変化するかもしれない。たとえば30ビットの実装では、536,870,911を左にシフトすると-2が生成されます。

(lsh 536870911 1)          ; 左シフト
     ⇒ -2

2進ではこの引数は以下のようになる:

;; 10進の536,870,911
0111...111111 (全部で30ビット)

これを左にシフトすると以下のようになる:

;; 10進の-2
1111...111110 (全部で30ビット)

Function: ash integer1 count

ash (算術シフト(arithmetic shift))は、integer1の中のビット位置を左にcountシフトする。countが負なら右にシフトする。

ashはlshと同じ結果を与えるが、例外はinteger1とcountがいずれも負の場合である。この場合、lshは左にできる空きビットに0、ashは1を置く。

したがってashでビットパターンの位置を右に1シフトすると以下のようになる:

(ash -6 -1) ⇒ -3
;; 10進の-6は10進の-3になる
1111...111010 (30 bits total)
     ⇒
1111...111101 (30 bits total)

対照的に、lshでビットパターンの位置を1右にシフトすると以下のようになる:

(lsh -6 -1) ⇒ 536870909
;; 10進の-6は10進の536,870,909になる
1111...111010 (30 bits total)
     ⇒
0111...111101 (30 bits total)

他にも例を示す:

                   ;         30ビットの2進数

(lsh 5 2)          ;   5  =  0000...000101
     ⇒ 20         ;      =  0000...010100

(ash 5 2)
     ⇒ 20
(lsh -5 2)         ;  -5  =  1111...111011
     ⇒ -20        ;      =  1111...101100
(ash -5 2)
     ⇒ -20

(lsh 5 -2)         ;   5  =  0000...000101
     ⇒ 1          ;      =  0000...000001

(ash 5 -2)
     ⇒ 1

(lsh -5 -2)        ;  -5  =  1111...111011
     ⇒ 268435454
                   ;      =  0011...111110

(ash -5 -2)        ;  -5  =  1111...111011
     ⇒ -2         ;      =  1111...111110

Function: logand &rest ints-or-markers

この関数は引数のビットのANDをリターンする。すべての引数のn番目のビットが1の場合に限り、結果のn番目のビットが1となる。

たとえば13と12では、4ビット2進数を使用すると1101と1100のビットANDは1100を生成する。この2進数ではいずれも左の2ビットがセット(つまり1)されているので、リターンされる値の左2ビットがセットされる。しかし右の2ビットにたいしては少なくとも1つの引数でそのビットが0なので、リターンされる値の右2ビットは0になる。

したがって、

(logand 13 12)
     ⇒ 12

logandに何も引数も渡さなければ、値-1がリターンされる。-1を2進数で表すとすべてのビットが1なので、-1はlogandにたいする単位元(identity element)である。

                   ;        30ビット2進数

(logand 14 13)     ; 14  =  0000...001110
                   ; 13  =  0000...001101
     ⇒ 12         ; 12  =  0000...001100

(logand 14 13 4)   ; 14  =  0000...001110
                   ; 13  =  0000...001101
                   ;  4  =  0000...000100
     ⇒ 4          ;  4  =  0000...000100

(logand)
     ⇒ -1         ; -1  =  1111...111111

Function: logior &rest ints-or-markers

この関数は、引数のビット単位の包含的ORをリターンする。少なくとも1つの引数でn番目のビットが1なら、結果のn番目のビットが1になる。引数を与えなければ、結果はこの処理にたいする単位元である0となる。logiorに渡す引数が1つだけならその引数がリターンされる。

                   ;        30ビット2進数

(logior 12 5)      ; 12  =  0000...001100
                   ;  5  =  0000...000101
     ⇒ 13         ; 13  =  0000...001101

(logior 12 5 7)    ; 12  =  0000...001100
                   ;  5  =  0000...000101
                   ;  7  =  0000...000111
     ⇒ 15         ; 15  =  0000...001111

Function: logxor &rest ints-or-markers

この関数は、引数のビット単位の排他的ORをリターンする。n番目のビットが1であるような引数の数が奇数個の場合のみ、結果のn番目のビットが1となる。引数を与えなければ、結果はこの処理の単位元である0となる。logxorに渡す引数が1つだけならその引数がリターンされる。

                   ;        30ビット2進数

(logxor 12 5)      ; 12  =  0000...001100
                   ;  5  =  0000...000101
     ⇒ 9          ;  9  =  0000...001001

(logxor 12 5 7)    ; 12  =  0000...001100
                   ;  5  =  0000...000101
                   ;  7  =  0000...000111
     ⇒ 14         ; 14  =  0000...001110

Function: lognot integer

この関数は引数のビット単位の補数(bitwise complement)をリターンする。integerのn番目のビットが0の場合に限り、結果のn番目のビットが1になり、その逆も成り立つ。

(lognot 5)
     ⇒ -6
;;  5  =  0000...000101 (全部で30ビット)
;; becomes
;; -6  =  1111...111010 (全部で30ビット)

3.9 標準的な数学関数

以下の数学的関数は、引数として整数と同様に浮動小数点数も受け入れます。

Function: sin arg
Function: cos arg
Function: tan arg: これらは三角関数であり、引数argはラジアン単位。

Function: asin arg: (asin arg)の値は、sinの値がargとなるような -pi/2 から pi/2 (両端を含む)の数である。argが範囲外([-1, 1]の外)なら、asinはNaNをリターンする。

Function: acos arg: (acos arg)の値は、cosの値がargとなるような、0から pi (両端を含む)の数である。argが範囲外([-1, 1]の外)ならacosはNaNをリターンする。

Function: atan y &optional x: (atan y)の値は、tanの値がyとなるような、 -pi/2 から pi/2 (両端を含まず)の数である。オプションの第2引数xが与えられると、(atan y x)の値はベクトル[x, y]とX軸が成す角度のラジアン値となる。

Function: exp arg: これは指数関数である。この関数はeの指数argをリターンする。

Function: log arg &optional base: この関数は底をbaseとするargの対数をリターンする。baseを指定しなければ、自然底(natural base)eが使用される。argかbaseが負なら、logはNaNをリターンする。

Function: expt x y: この関数はxにyを乗じてリターンする。引数が両方とも整数でyが正なら結果は整数になる。この場合オーバーフローによる切り捨てが発生するので注意しされたい。xが有限の負数でyが有限の非整数なら、exptはNaNをリターンする。

Function: sqrt arg: これはargの平方根をリターンする。argが有限で0より小さければ、sqrtはNaNをリターンする。

加えて、Emacsは以下の数学的な定数を定義します:

Variable: float-e: 自然対数e(2.71828…)

Variable: float-pi: 円周率pi(3.14159…)

3.10 乱数

決定論的なコンピュータープログラムでは真の乱数を生成することはできません。しかしほとんどの目的には、疑似乱数(pseudo-random numbers)で充分です。一連の疑似乱数は決定論的な手法により生成されます。真の乱数ではありませんが、それらにはランダム列を模する特別な性質があります。たとえば疑似ランダム系では、すべての可能な値は均等に発生します。

疑似乱数はシード値(seed value)から生成されます。与えられた任意のシードから開始することにより、random関数は常に同じ数列を生成します。デフォルトでは、Emacsは開始時に乱数シードを初期化することにより、それぞれのEmacsの実行において、randomの値シーケンスは(ほとんど確実に)異なります。

再現可能な乱数シーケンスが欲しい場合もあります。たとえば乱数シーケンスに依存するプログラムをデバッグする場合、プログラムの各実行において同じ挙動を得ることが助けになります。再現可能なシーケンスを作成するには、(random "")を実行します。これは特定のEmacsの実行可能ファイルにたいして、シードに定数値をセットします(しかしこの実行可能ファイルは、その他のEmacsビルドと異なるものになるであろう)。シード値として、他のさまざまな文字列を使用することができます。

Function: random &optional limit

この関数は疑似乱数の整数をリターンする。繰り返し呼び出すと一連の疑似乱数の整数をリターンする。

limitが正なら、値は負ではないlimit未満の値から選択される。それ以外なら値はmost-negative-fixnumからmost-positive-fixnumの間の、Lispで表現可能な任意の整数(整数の基礎を参照)となるだろう。

limitがtなら、あたかもEmacsが再起動されたかのように、通常はシステムのエントロピーから新たなシードが選択されることを意味する。エントロピープールを欠くシステムでは、カレント時刻のような若干揮発性が低い乱数からシードが選択される。

limitが文字列なら、その文字列定数にもとづいた新しいシードを選択することを意味する。

4 文字列と文字

Emacs Lispの文字列は、文字列の順序列(ordered sequence)を含む配列です。文字列はシンボル、バッファー、ファイルの名前に使用されます。その他にもユーザーにたいしてメッセージを送ったりバッファー間でコピーする文字列を保持したり等、多くの目的に使用されます。文字列は特に重要なので、Emacs Lispは特別には文字列を操作するために多くの関数があります。Emacs Lispプログラムでは個々の文字より文字列を多用します。

キーボードの文字イベントの文字列にたいする特別な考慮は、文字列内へのキーボードイベントの配置を参照してください。

4.1 文字列と文字の基礎		文字列と文字の基本的なプロパティー。
4.2 文字列のための述語		オブジェクトが文字列か文字かをテストする。
4.3 文字列の作成		新しい文字列を割り当てる関数。
4.4 文字列の変更		既存の文字列の内容を変更する。
4.5 文字および文字列の比較		文字または文字列を比較する。
4.6 文字および文字列の変換		文字から文字列への変換と逆変換。
4.7 文字列のフォーマット		`format`: `printf`のEmacs版。
4.8 Lispでの大文字小文字変換		大文字小文字の変換関数。
4.9 caseテーブル		case変換のカスタマイズ。

4.1 文字列と文字の基礎

文字(character)とは、テキスト内の1つの文字を表すLispオブジェクトです。Emacs Lispでは文字は単なる整数です。ある整数が文字か文字でないかを区別するのは、それが使用される方法だけです。Emacsでの文字表現についての詳細は文字コードを参照してください。

文字列(string)とは固定された文字シーケンスです。これは配列(array)と呼ばれるシーケンス型であり、配列長が固定で一度作成したら変更できないことを意味します(シーケンス、配列、ベクターを参照)。Cとは異なり、Emacs Lispの文字列は文字コードを判断することにより終端されません。

文字列は配列であるということは同様にシーケンスでもあるので、シーケンス、配列、ベクターにドキュメントされている一般的な配列関数やシーケンス関数で文字列を処理できます。たとえば文字列内の特定の文字にアクセスしたり変更することができます。しかし表示された文字列の幅を計算するために、lengthを使用するべきではないことに注意してください。かわりにstring-widthを使用してください(表示されるテキストのサイズを参照)。

Emacs文字列での非ASCIIにたいすテキスト表現は2つ — ユニバイト(unibyte)とマルチバイト(multibyte)があります。ほとんどのLispプログラミングでは、これら2つの表現を気にする必要はありません。詳細はテキストの表現方法を参照してください。

キーシーケンスがユニバイト文字列で表されることがあります。ユニバイト文字列がキーシーケンスの場合、範囲128から255までの文字列要素は範囲128から255の文字コードではなく、メタ文字(これは非常に大きな整数である)を表します。文字列はハイパー(hyper)、スーパー(super)、アルト(alt)で修飾された文字を保持できません。文字列はASCIIコントロール文字を保持できますが、それは他のコントロール文字です。文字列はASCIIコントロール文字のcaseを区別できません。そのような文字をシーケンスに保存したい場合は、文字列ではなくベクターを使用しなければなりません。キーボード入力文字についての情報は文字型を参照してください。

文字列は正規表現を保持するために便利です。string-match (正規表現の検索を参照)を使用して、文字列にたいして正規表現をマッチすることもできます。関数match-string (単純なマッチデータへのアクセスを参照)とreplace-match (マッチしたテキストの置換を参照)は、文字列にたいして正規表現をマッチした後に、文字列を分解・変更するのに便利です。

バッファーのように、文字列は文字列内の文字自身とその文字にたいするテキストプロパティーを含みます。テキストのプロパティを参照してください。文字列からバッファーや他の文字列にテキストをコピーする、すべてのLispプリミティブ(Lisp primitives)はコピーされる文字のプロパティーもコピーします。

文字列の表示やバッファーにコピーする関数についての情報はテキストを参照してください。文字または文字列の構文についての情報は、文字型と文字列型を参照してください。異なるテキスト表現間で変換したり、文字コードをエンコード、デコードする関数については非ASCII文字を参照してください。

4.2 文字列のための述語

一般的なシーケンスや配列にたいする述語についての情報は、シーケンス、配列、ベクターと配列を参照してください。

Function: stringp object: この関数はobjectが文字列ならt、それ以外はnilをリターンする。

Function: string-or-null-p object: この関数はobjectが文字列かnilならt、それ以外はnilをリターンする。

Function: char-or-string-p object: この関数はobjectが文字列か文字(たとえば整数)ならt、それ以外はnilをリターンする。

4.3 文字列の作成

以下の関数は新たに文字列を作成したり、文字列同士の結合による文字列の作成や、文字列の一部から文字列を作成する関数です。

Function: make-string count character

この関数はcharacterをcount回繰り返すことにより作成された文字列をリターンする。countが負ならエラーをシグナルする。

(make-string 5 ?x)
     ⇒ "xxxxx"
(make-string 0 ?x)
     ⇒ ""

この関数に対応する他の関数にはmake-vector (ベクターを参照)やmake-list (コンスセルおよびリストの構築を参照)が含まれる。

Function: string &rest characters

この関数は文字charactersを含む文字列をリターンする。

(string ?a ?b ?c)
     ⇒ "abc"

Function: substring string &optional start end

この関数はstringから、インデックスstartの文字(その文字を含む)とendの文字(その文字は含まない)の間の範囲の文字で構成される、新しい文字列をリターンする。文字列の最初の文字はインデックス0。引数が1つなら、この関数は単にstringをコピーする。

(substring "abcdefg" 0 3)
     ⇒ "abc"

上記の例では‘a’のインデックスは0、‘b’のインデックスは1、‘c’のインデックスは2となる。インデックス3 — この文字列の4番目の文字 — は、コピーされる部分文字列の文字位置までをマークする。したがって文字列"abcdefg"から‘abc’がコピーされる。

負の数は文字列の最後から数えることを意味するので、-1は文字列の最後の文字のインデックスである。たとえば:

(substring "abcdefg" -3 -1)
     ⇒ "ef"

この例では‘e’のインデックスは-3、‘f’のインデックスは-2、‘g’のインデックスは-1。つまり‘e’と‘f’が含まれ、‘g’は含まれない。

endにnilを使用した場合、それは文字列の長さを意味する。したがって、

(substring "abcdefg" -3 nil)
     ⇒ "efg"

引数endを省略した場合、それはnilを指定したのと同じである。(substring string 0)はstringのすべてをコピーしてリターンする。

(substring "abcdefg" 0)
     ⇒ "abcdefg"

しかしこの目的のためにはcopy-sequenceを推奨する(シーケンスを参照)。

stringからコピーされた文字がテキストプロパティーをもつなら、そのプロパティーは新しい文字列へもコピーされる。テキストのプロパティを参照のこと。

substringの最初の引数にはベクターも指定できる。たとえば:

(substring [a b (c) "d"] 1 3)
     ⇒ [b (c)]

startが整数でない、またはendが整数でもnilでもななければ、wrong-type-argumentエラーがシグナルされる。startがendの後の文字を指す、またはstringにたいして範囲外の整数をいずれかに指定すると、args-out-of-rangeエラーがシグナルされる。

この関数に対応するのはbuffer-substring (バッファーのコンテンツを調べるを参照)で、これはカレントバッファー内のテキストの一部を含む文字列をリターンする。文字列の先頭はインデックス0だが、バッファーの先頭はインデックス1である。

Function: substring-no-properties string &optional start end: これはsubstringと同じように機能するが、値のすべてのテキストプロパティーを破棄する。startを省略したりnilを指定することができ、その場合は0と等価だる。したがって(substring-no-properties string)は、すべてのテキストプロパティーが削除されたstringのコピーをリターンする。

Function: concat &rest sequences

この関数は渡された引数内の文字からなる、新しい文字列をリターンする(もしあればテキストプロパティーも)。引数には文字列、数のリスト、数のベクターを指定できる。引数は変更されない。concatに引数を指定しなければ空文字列をリターンする。

(concat "abc" "-def")
     ⇒ "abc-def"
(concat "abc" (list 120 121) [122])
     ⇒ "abcxyz"
;; nilhあ空のシーケンス。
(concat "abc" nil "-def")
     ⇒ "abc-def"
(concat "The " "quick brown " "fox.")
     ⇒ "The quick brown fox."
(concat)
     ⇒ ""

この関数は常に、任意の既存文字列にたいしてeqではない、新しい文字列を構築するが、結果が空文字列の時を除く(スペース省略のためにEmacsは空のマルチバイト文字列を1つだけ作成する)。

他の結合関数(concatenation functions)についての情報は関数のマッピングのmapconcat、ベクターのための関数のvconcat、コンスセルおよびリストの構築のappendを参照のこと。シェルコマンドで使用される文字列の中に、個々のコマンドライン引数を結合するには、combine-and-quote-stringsを参照されたい。

Function: split-string string &optional separators omit-nulls trim

この関数は正規表現separators(正規表現を参照)にもとづいて、stringを部分文字列に分解する。separatorsにたいする各マッチは分割位置を定義する。分割位置の間にある部分文字列をリストにまとめてリターンする。

If separators is nil (or omitted), the default is the value of split-string-default-separators and the function behaves as if omit-nulls were t.

omit-nullsがnil(または省略)なら、連続する2つのseparatorsへのマッチか、stringの最初か最後にマッチしたときの空文字列が結果に含まれる。omit-nullsがtなら、これらの空文字列は結果から除外される。

オプションの引数trimが非nilなら、その値は各部分文字列の最初と最後からトリム(trim: 除去)するテキストにマッチする正規表現を指定する。トリムによりその部分文字列が空になるようなら、それは空文字列として扱われる。

文字列を分割してcall-processやstart-processに適するような、個々のコマンドライン引数のリストにする必要がある場合は、split-string-and-unquoteを参照されたい。

Examples:

(split-string "  two words ")
     ⇒ ("two" "words")

有用性はほとんどないであろう("" "two" "words" "")という結果とはならない。このような結果が必要ならseparatorsに明示的な値を使用すること

(split-string "  two words "
              split-string-default-separators)
     ⇒ ("" "two" "words" "")

(split-string "Soup is good food" "o")
     ⇒ ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o" t)
     ⇒ ("S" "up is g" "d f" "d")
(split-string "Soup is good food" "o+")
     ⇒ ("S" "up is g" "d f" "d")

空のマッチはカウントされます。例外は、空でないマッチを使用することにより、すでに文字列の最後に到達しているとき、またはstringが空の時で、この場合split-stringは最後の空マッチを探しません。

(split-string "aooob" "o*")
     ⇒ ("" "a" "" "b" "")
(split-string "ooaboo" "o*")
     ⇒ ("" "" "a" "b" "")
(split-string "" "")
     ⇒ ("")

しかしseparatorsが空文字列にマッチできるとき、通常はomit-nullsをtにすれば、前の3つの例の不明瞭さはほとんど発生しない:

(split-string "Soup is good food" "o*" t)
     ⇒ ("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "" t)
     ⇒ ("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
(split-string "" "" t)
     ⇒ nil

空でないマッチより空のマッチを優先するような、一部の“非貪欲(non-greedy)”な値をseparatorsに指定することにより、幾分奇妙(ではあるが予見可能)な振る舞いが発生することがある。繰り返しになるが、そのような値は実際には稀である:

(split-string "ooo" "o*" t)
     ⇒ nil
(split-string "ooo" "\\|o+" t)
     ⇒ ("o" "o" "o")

Variable: split-string-default-separators: split-stringのseparatorsにたいするデフォルト値。通常の値は"[ \f\t\n\r\v]+"。

4.4 文字列の変更

既存の文字列の内容を変更するもっとも基本的な方法は、aset (配列を操作する関数を参照)を使用する方法です。(aset string idx char)は、stringのインデックスidxに、charを格納します。それぞれの文字は1文字以上を占有しますが、すでにインデックスの場所にある文字のバイト数がcharが要するバイト数と異なる場合、asetはエラーをシグナルします。

より強力な関数はstore-substringです:

Function: store-substring string idx obj

この関数はインデックスidxで開始される位置にobjを格納することにより、文字列stringの内容の一部を変更する。objは文字、または(stringより小さい)文字列です。

既存の文字列の長さを変更するのは不可能なので、stringの実際の長さにobjが収まらない、またはstringのその位置に現在ある文字のバイト数が新しい文字に必要なバイト数と異なる場合はエラーになる。

パスワードを含む文字列をクリアーするときにはclear-stringを使用します:

Function: clear-string string: これはstringをユニバイト文字列にして、内容を0にクリアーする。これによりstringの長さも変更されるだろう。

4.5 文字および文字列の比較

Function: char-equal character1 character2

この関数は引数が同じ文字を表すならt、それ以外はnilをリターンする。case-fold-searchが非nilなら、この関数はcaseの違いを無視する。

(char-equal ?x ?x)
     ⇒ t
(let ((case-fold-search nil))
  (char-equal ?x ?X))
     ⇒ nil

Function: string= string1 string2

この関数は、2つの文字列の文字が正確にマッチすればtをリターンする。引数にはシンボルも指定でき、この場合はそのシンボル名が使用される。case-fold-searchとは無関係にcaseは常に意味をもつ。

この関数は、equalで2つの文字列を比較するのと等価である(同等性のための述語を参照)。特に、2つの文字列のテキストプロパティーは無視されます。テキストプロパティーだけが異なる文字列を区別する必要があるならequal-including-propertiesを使用すること。しかしequalとは異なり、いずれかの引数が文字列でもシンボルでもなければ、string=はエラーをシグナルする。

(string= "abc" "abc")
     ⇒ t
(string= "abc" "ABC")
     ⇒ nil
(string= "ab" "ABC")
     ⇒ nil

技術的な理由によりユニバイト文字列とマルチバイト文字列がequalになるのは、それらが同じ文字コードのシーケンスを含み、それらすべてのコードが0から127(ASCII)、または160から255(eight-bit-graphic)のときだけである。しかしユニバイト文字列をマルチバイト文字列に変更する際、コードが160から255の範囲にあるすべての文字はより高いコードに変換され、ASCII文字は変換されないまま残る。したがってユニバイト文字列とそれを変換したマルチバイト文字列は、その文字列のすべてがASCIIのときだけequalとなる。もしマルチバイト文字列中で文字コード160から255の文字があったとしても、それは完全に正しいとは言えない。結果として、すべてがASCIIではないユニバイト文字列とマルチバイト文字列がequalという状況は、もしかしたらEmacs Lispプロプラマーが直面するかもしれない、とても稀で記述的に不可解な状況だといえよう。テキストの表現方法を参照されたい。

Function: string-equal string1 string2: string-equalはstring=の別名である。

Function: string-collate-equalp string1 string2 &optional locale ignore-case

この関数は照合ルール(collation rules)にもとづいてstring1とstring2が等しければtをリターンする。照合ルールはstring1とstring2に含まれる文字の辞書順だけではなく、それらの文字間の関係に関する他のルールにより判断される。これは通常は、Emacs実行中のlocale環境により決定される。

たとえば異なるコーディングポイントでも、Unicodeのグレイブアクセント文字のように同じ意味なら等しいとみなされる。

(string-collate-equalp (string ?\uFF40) (string ?\u1FEF))
     ⇒ t

オプション引数locale(文字列)は、照合用のカレントlocale識別子(current locale identifier)をオーバーライドする。値はシステムに依存する。たとえばPOSIXシステムでは"en_US.UTF-8"、MS-Windowsシステムでは"enu_USA.1252"のlocaleが適用できるだろう。

ignore-caseが非nilなら、それらは比較前に小文字に変換される。

MS-WindowsシステムでUnicode互換の照合をエミュレートする場合、MS-Windowsではlocaleのコードセット部分を"UTF-8"にできないので、w32-collate-ignore-punctuationに非nil値をバインドすること。

あるlocale環境をシステムがサポートしなれければ、この関数はstring-equalと同様に振る舞う。

一般的にファイルシステムは照合ルールが実装するような文字列の言語学的な等価性を尊重しないので、この関数をファイル名の等価性の比較に使用しないこと。

Function: string< string1 string2

この関数は2つの文字列を1文字ずつ比較する。この関数は同時に2つの文字列をスキャンして、対応する文字同士がマッチしない最初のペアを探す。2つの文字列内で小さいほうの文字がstring1の文字ならstring1が小さいことになり、この関数はtをリターンする。小さいほうの文字がstring2の文字ならstring1が大きいことになり、この関数はnilをリターンする。2つの文字列が完全にマッチしたら値はnilになる。

文字のペアーは文字コードで比較されル。ASCII文字セットでは英小文字は英大文字より高い数値をもつことに留意されたい。数字と区切り文字の多くは英大文字より低い数値をもつ。ASCII文字は任意の非ASCII文字より小さくなる。ユニバイトの非ASCII文字は、任意のマルチバイト非ASCII文字より常に小さくなります(テキストの表現方法を参照)。

(string< "abc" "abd")
     ⇒ t
(string< "abd" "abc")
     ⇒ nil
(string< "123" "abc")
     ⇒ t

文字列の長さが異なり、string1の長さまでマッチする場合、結果はtになる。string2の長さまでマッチする場合、結果はnilになる。文字を含まない文字列は、他の任意の文字列より小さくなる。

(string< "" "abc")
     ⇒ t
(string< "ab" "abc")
     ⇒ t
(string< "abc" "")
     ⇒ nil
(string< "abc" "ab")
     ⇒ nil
(string< "" "")
     ⇒ nil

引数としてシンボルを指定することもでき、この場合はシンボルのプリント名が比較される。

Function: string-lessp string1 string2: string-lesspはstring<の別名である。

Function: string-greaterp string1 string2: この関数は逆順でstring1とstring2を比較した結果をリタンーする。つまりこれは(string-lessp string2 string1)を呼び出すのと等価である。

Function: string-collate-lessp string1 string2 &optional locale ignore-case

この関数は照合順でstring1がstring2より小さければtをリターンする。照合順はstring1とstring2に含まれる文字の辞書順だけではなく、それらの文字間の関係に関するルールによっても判断される。これは通常はEmacs実行中のlocale環境により決定される。

たとえばソートでは区切り文字と空白文字は無視されるだろう(シーケンスを参照)。

(sort '("11" "12" "1 1" "1 2" "1.1" "1.2") 'string-collate-lessp)
     ⇒ ("11" "1 1" "1.1" "12" "1 2" "1.2")

Cygwinではlocaleと無関係に区切り文字と空白文字が無視されることが決してないように、この振る舞いはシステム依存である。

(sort '("11" "12" "1 1" "1 2" "1.1" "1.2")
      (lambda (s1 s2) (string-collate-lessp s1 s2 "POSIX")))
     ⇒ ("1 1" "1 2" "1.1" "1.2" "11" "12")

ignore-caseが非nilなら、それらは比較前に小文字に変換される。

locale環境をサポートしないシステムでは、この関数はstring-lesspと同様に振る舞う。

Function: string-version-lessp string1 string2: This function compares strings lexicographically, except it treats sequences of numerical characters as if they comprised a base-ten number, and then compares the numbers. So ‘foo2.png’ is “smaller” than ‘foo12.png’ according to this predicate, even if ‘12’ is lexicographically “smaller” than ‘2’.

Function: string-prefix-p string1 string2 &optional ignore-case: この関数はstring1がstring2のプレフィクス(たとえばstring2がstring1で始まる)なら、非nilをリターンする。オプションの引数ignore-caseが非nilばら、比較においてcaseの違いは無視される。

Function: string-suffix-p suffix string &optional ignore-case: この関数はsuffixがstringのサフィックス(たとえばstringがsuffixで終わる)なら、非nilをリターンする。オプションの引数ignore-caseが非nilなら、比較においてcaseの違いは無視される。

Function: compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case

この関数はstring1の指定部分をとstring2指定部分を比較する。string1の指定部分とは、インデックスstart1(その文字を含む)から、インデックスend1(その文字を含まない)まで。start1にnilを指定すると文字列の最初という意味になり、end1にnilを指定すると文字列の長さを意味する。同様にstring2の指定部分とはインデックスstart2からインデックスend2まで。

文字列は文字列内の文字の数値により比較される。たとえばstr1とstr2は、最初に異なる文字でstr1の文字の数値が小さければ小さいと判断される。ignore-caseが非nilなら比較を行なう前に大文字に変換される。比較用にユニバイト文字列はマルチバイト文字列に変換されるので(テキストの表現方法を参照)、ユニバイト文字列とそれを変換したマルチバイト文字列は常に等しくなる。

2つの文字列の指定部分がマッチした場合、値はtになる。それ以外なら値は整数で、何文字が一致してどちらの文字が小さいかを示す。この値の絶対値は、2つの文字列の先頭から一致した文字数に1加えた値になる。string1(または指定部分)のほうが小さければ符号は負になる。

Function: assoc-string key alist &optional case-fold: この関数はassocと同様に機能するが、keyは文字列かシンボルでなければならず、比較はcompare-stringsを使用して行なわれる。テストする前にシンボルは文字列に変換される。case-foldが非nilなら、keyとalistの要素は比較前に大文字に変換される。assocとは異なり、この関数はコンスではない文字列またはシンボルのalist要素もマッチできる。特にalistは実際のalistではなく、文字列またはリストでも可。連想リストを参照のこと。

バッファー内のテキストを比較する方法として、テキストの比較の関数compare-buffer-substringsも参照してください。文字列にたいして正規表現のマッチを行なう関数string-matchも、ある種の文字列比較に使用することができます。正規表現の検索を参照してください。

4.6 文字および文字列の変換

このセクションでは文字、文字列、整数の間で変換を行なう関数を説明します。format (文字列のフォーマットを参照)とprin1-to-string (出力関数を参照)もLispオブジェクトを文字列に変換できます。read-from-string (入力関数を参照)は、Lispオブジェクトの文字列表現をオブジェクトに“変換”できます。関数string-to-multibyteとstring-to-unibyteは、テキスト表現を文字列に変換します(テキスト表現の変換を参照)。

テキスト文字と一般的なインプットイベントにたいするテキスト記述を生成する関数(single-key-descriptionとtext-char-description)については、ドキュメントを参照してください。これらの関数は主にヘルプメッセージを作成するために使用されます。

Function: number-to-string number

この関数はnumberの10進プリント表現からなる文字列をリターンする。引数が負ならリターン値はマイナス記号から開始される。

(number-to-string 256)
     ⇒ "256"

(number-to-string -23)
     ⇒ "-23"

(number-to-string -23.5)
     ⇒ "-23.5"

int-to-stringはこの関数にたいする半ば廃れたエイリアスである。

文字列のフォーマットの関数formatも参照されたい。

Function: string-to-number string &optional base

この関数はstring内の文字の数値的な値をリターンする。baseが非nilなら値は2以上16以下でなければならず、整数はその基数に変換される。baseがnilなら基数に10が使用される。浮動少数点数の変換は基数が10のときだけ機能する。わたしたちは浮動小数点数にたいして他の基数を実装しない。なぜならこれには多くの作業を要し、その割にその機能が有用には思えないからだ。stringが整数のように見えるが、その値がLispの整数に収まらないほど大きな値なら、string-to-numberは浮動小数点数の結果をリターンする。

パースではstringの先頭にあるスペースとタブはスキップして、与えられた基数で数字として解釈できるところまでstringを読み取る(スペースとタブだけではなく先頭にある他の空白文字を無視するシステムもある)。stringを数字として解釈できなければこの関数は0をリターンする。

(string-to-number "256")
     ⇒ 256
(string-to-number "25 is a perfect square.")
     ⇒ 25
(string-to-number "X256")
     ⇒ 0
(string-to-number "-4.5")
     ⇒ -4.5
(string-to-number "1e5")
     ⇒ 100000.0

string-to-intはこの関数にたいする半ば廃れたエイリアスである。

Function: char-to-string character: この関数は1つの文字characterを含む新しい文字列をリターンする。関数stringのほうがより一般的であり、この関数は半ば廃れている。文字列の作成を参照のこと。

Function: string-to-char string: この関数はstringの最初の文字をリターンする。これはほとんど(aref string 0)と同じで、例外は文字列が空のときに0をリターンすること(文字列の最初の文字がASCIIコード0のヌル文字のときも0をリターンする)。この関数は残すのに充分なほど有用と思えないければ、将来削除されるかもしれない。

以下は文字列へ／からの変換に使用できるその他の関数です:

concat: この関数はベクターまたはリストから文字列に変換する。文字列の作成を参照のこと。
vconcat: この関数は文字列をベクターに変換する。ベクターのための関数を参照のこと。
append: この関数は文字列をリストに変換する。コンスセルおよびリストの構築を参照のこと。
byte-to-string: この関数は文字データのバイトをユニバイト文字列に変換する。テキスト表現の変換を参照のこと。

4.7 文字列のフォーマット

フォーマット(formatting)とは、定数文字列内のなまざまな場所を計算された値で置き換えることにより、文字列を構築することを意味します。この定数文字列は他の値がプリントされる方法、同様にどこに表示するかを制御します。これはフォーマット文字列(format string)と呼ばれます。

表示されるメッセージを計算するためにフォーマットが便利なことがしばしばあります。実際に関数messageとerrorは、ここで説明する機能と同じフォーマットを提供します。これらの関数とformat-messageの違いはフォーマットされた結果を使用する方法だけです。

Function: format string &rest objects

This function returns a string equal to string, replacing any format specifications with encodings of the corresponding objects. The arguments objects are the computed values to be formatted.

The characters in string, other than the format specifications, are copied directly into the output, including their text properties, if any. Any text properties of the format specifications are copied to the produced string representations of the argument objects.

The output string need not be newly-allocated. For example, if x is the string "foo", the expressions (eq x (format x)) and (eq x (format "%s" x)) might both yield t.

Function: format-message string &rest objects

This function acts like format, except it also converts any grave accents (`) and apostrophes (') in string as per the value of text-quoting-style.

Typically grave accent and apostrophe in the format translate to matching curved quotes, e.g., "Missing `%s'" might result in "Missing ‘foo’". See section Text Quoting Style, for how to influence or inhibit this translation.

フォーマット仕様(format specification)は‘%’で始まる文字シーケンスです。したがってstring内に‘%d’がるとformatはそれを、フォーマットされる値の1つ(引数objectsのうちの1つ)にたいするプリント表現で置き換えます。たとえば:

(format "The value of fill-column is %d." fill-column)
     ⇒ "The value of fill-column is 72."

formatは文字‘%’をフォーマット仕様と解釈するので、決して最初の引数に不定な文字列(arbitrary string)を渡すべきではありません。これは特に何らかのLispコードga生成siた文字列の場合に当てはまります。その文字列が決して文字‘%’を含まないと確信できないならば、以下で説明するように最初の引数に"%s"を渡して、不定な文字列を2番目の引数として渡します:

  (format "%s" arbitrary-string)

ある種のフォーマット仕様は特定の型の値を要求します。その要求に適合しない値を与えた場合にはエラーがシグナルされます。

以下は有効なフォーマット仕様のテーブルです:

‘%s’

フォーマット仕様を、クォートなしのオブジェクトのプリント表現で置き換える(つまりprin1ではなくprincを使用して置き換える。出力関数を参照されたい)。したがって文字列は‘"’文字なしの文字列内容だけが表示され、シンボルは‘\’文字なしで表される。

オブジェクトが文字列なら文字列のプロパティーは出力にコピーされる。‘%s’のテキストプロパティー自身もコピーされるが、オブジェクトのテキストプロパティーが優先される。

‘%S’

フォーマット仕様を、クォートありのオブジェクトのプリント表現で置き換える(つまりprin1を使用して変換する。出力関数を参照されたい)。したがって文字列は‘"’文字で囲まれ、必要となる特別文字の前に‘\’文字が表示される。

‘%o’

Replace the specification with the base-eight representation of an unsigned integer.

‘%d’

Replace the specification with the base-ten representation of a signed integer.

‘%x’

‘%X’

Replace the specification with the base-sixteen representation of an unsigned integer. ‘%x’ uses lower case and ‘%X’ uses upper case.

‘%c’

フォーマット仕様を与えられた値の文字で置き換える。

‘%e’

フォーマット仕様を浮動小数点数の指数表現で置き換える。

‘%f’

フォーマット仕様を浮動小数点数にたいする10進少数表記で置き換える。

‘%g’

Replace the specification with notation for a floating-point number, using either exponential notation or decimal-point notation. The exponential notation is used if the exponent would be less than -4 or greater than or equal to the precision (default: 6). By default, trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.

‘%%’

Replace the specification with a single ‘%’. This format specification is unusual in that its only form is plain ‘%%’ and that it does not use a value. For example, (format "%% %d" 30) returns "% 30".

他のフォーマット文字は‘Invalid format operation’エラーとなります。

以下は典型的なtext-quoting-styleのセッティングを想定した場合の例です:

(format "The octal value of %d is %o,
         and the hex value is %x." 18 18 18)
     ⇒ "The octal value of 18 is 22,
         and the hex value is 12."

(format-message
 "The name of this buffer is ‘%s’." (buffer-name))
     ⇒ "The name of this buffer is ‘strings.texi’."

(format-message
 "The buffer object prints as `%s'." (current-buffer))
     ⇒ "The buffer object prints as ‘strings.texi’."

By default, format specifications correspond to successive values from objects. Thus, the first format specification in string uses the first such value, the second format specification uses the second such value, and so on. Any extra format specifications (those for which there are no corresponding values) cause an error. Any extra values to be formatted are ignored.

A format specification can have a field number, which is a decimal number immediately after the initial ‘%’, followed by a literal dollar sign ‘$’. It causes the format specification to convert the argument with the given number instead of the next argument. Field numbers start at 1. A format can contain either numbered or unnumbered format specifications but not both, except that ‘%%’ can be mixed with numbered specifications.

(format "%2$s, %3$s, %%, %1$s" "x" "y" "z")
     ⇒ "y, z, %, x"

After the ‘%’ and any field number, you can put certain flag characters.

フラグ‘+’は正の数の前にプラス符号を挿入するので、数には常に符号がつきます。フラグとしてスペースを指定すると、正数の前に1つのスペースが挿入されます(それ以外は、正数は最初の数字から開始される)。これらのフラグは、確実に正数と負数が同じ列数を使用させるために有用です。これらは‘%d’、‘%e’、‘%f’、‘%g’以外では無視され、両方が指定された場合は‘+’が優先されます。

The flag ‘#’ specifies an alternate form which depends on the format in use. For ‘%o’, it ensures that the result begins with a ‘0’. For ‘%x’ and ‘%X’, it prefixes the result with ‘0x’ or ‘0X’. For ‘%e’ and ‘%f’, the ‘#’ flag means include a decimal point even if the precision is zero. For ‘%g’, it always includes a decimal point, and also forces any trailing zeros after the decimal point to be left in place where they would otherwise be removed.

フラグ‘0’はスペースの代わりに文字‘0’でパディングします。このフラグは‘%s’、‘%S’、‘%c’のような非数値のフォーマット仕様文字では無視されます。これらのフォーマット仕様文字で‘0’フラグを指定できますが、それでもスペースでパディングされます。

The flag ‘-’ causes any padding inserted by the width, if specified, to be inserted on the right rather than the left. If both ‘-’ and ‘0’ are present, the ‘0’ flag is ignored.

(format "%06d is padded on the left with zeros" 123)
     ⇒ "000123 is padded on the left with zeros"

(format "'%-6d' is padded on the right" 123)
     ⇒ "'123   ' is padded on the right"

(format "The word '%-7s' actually has %d letters in it."
        "foo" (length "foo"))
     ⇒ "The word 'foo    ' actually has 3 letters in it."

A specification can have a width, which is a decimal number that appears after any field number and flags. If the printed representation of the object contains fewer characters than this width, format extends it with padding. Any padding introduced by the width normally consists of spaces inserted on the left:

(format "%5d is padded on the left with spaces" 123)
     ⇒ "  123 is padded on the left with spaces"

フィールド幅が小さすぎる場合でもformatはオブジェクトのプリント表現を切り詰めません。したがって情報を失う危険を犯すことなく、フィールドの最小幅を指定することができます。以下の2つの例では‘%7s’は最小幅に7を指定します。1番目の例では‘%7s’に挿入される文字列は3文字だけなので、4つのブランクスペースによりパディングされます。2番目の例では文字列"specification"は13文字ですが切り詰めはされません。

(format "The word '%7s' has %d letters in it."
        "foo" (length "foo"))
     ⇒ "The word '    foo' has 3 letters in it."
(format "The word '%7s' has %d letters in it."
        "specification" (length "specification"))
     ⇒ "The word 'specification' has 13 letters in it."

All the specification characters allow an optional precision after the field number, flags and width, if present. The precision is a decimal-point ‘.’ followed by a digit-string. For the floating-point specifications (‘%e’ and ‘%f’), the precision specifies how many digits following the decimal point to show; if zero, the decimal-point itself is also omitted. For ‘%g’, the precision specifies how many significant digits to show (significant digits are the first digit before the decimal point and all the digits after it). If the precision of %g is zero or unspecified, it is treated as 1. For ‘%s’ and ‘%S’, the precision truncates the string to the given width, so ‘%.3s’ shows only the first three characters of the representation for object. For other specification characters, the effect of precision is what the local library functions of the printf family produce.

4.8 Lispでの大文字小文字変換

case変換関数(character case functions)は、1つの文字または文字列中の大文字小文字を変換します。関数は通常、アルファベット文字(英字‘A’から‘Z’と‘a’から‘z’、同様に非ASCIIの英字)だけを変換し、それ以外の文字は変換しません。caseテーブル(case table。caseテーブルを参照されたい)で指定することにより、caseの変換に異なるマッピングを指定できます。

これらの関数は引数として渡された文字列は変更しません。

以下の例では文字‘X’と‘x’を使用します。これらのASCIIコードは88と120です。

Function: downcase string-or-char

この関数はstring-or-char(文字か文字列)を小文字に変換する。

string-or-charが文字列なら、この関数は引数の大文字を小文字に変換した新しい文字列をリターンする。string-or-charが文字なら、この関数は対応する小文字(整数)をリターンする。元の文字が小文字か非英字ならリターン値は元の文字と同じ。

(downcase "The cat in the hat")
     ⇒ "the cat in the hat"

(downcase ?X)
     ⇒ 120

Function: upcase string-or-char

この関数はstring-or-char(文字か文字列)を大文字に変換する。

string-or-charが文字列なら、この関数は引数の小文字を大文字に変換した新しい文字列をリターンする。string-or-charが文字なら、この関数は対応する大文字(整数)をリターンする。元の文字が大文字か非英字ならリターン値は元の文字と同じ。

(upcase "The cat in the hat")
     ⇒ "THE CAT IN THE HAT"

(upcase ?x)
     ⇒ 88

Function: capitalize string-or-char

この関数は文字列や文字をキャピタライズ(capitalize: 先頭が大文字で残りは小文字)する。この関数はstring-or-charが文字列ならstring-or-charの各単語をキャピタライズした新たなコピーをリターンする。これは各単語の最初の文字が大文字に変換され、残りは小文字に変換されることを意味する。

単語の定義はカレント構文テーブル(current syntax table)の単語構成構文クラス(word constituent syntax class)に割り当てられた、連続する文字の任意シーケンスである(構文クラスのテーブルを参照)。

string-or-charが文字ならこの関数はupcaseと同じことを行なう。

(capitalize "The cat in the hat")
     ⇒ "The Cat In The Hat"

(capitalize "THE 77TH-HATTED CAT")
     ⇒ "The 77th-Hatted Cat"

(capitalize ?x)
     ⇒ 88

Function: upcase-initials string-or-char

この関数はstring-or-charが文字列なら、string-or-charの中の単語の頭文字をキャピタライズして、頭文字以外の文字は変更しない。この関数はstring-or-charの各単語の頭文字が大文字に変換された新しいコピーをリターンする。

upcase-initialsの引数が文字なら、upcase-initialsの結果はupcaseと同じ。

(upcase-initials "The CAT in the hAt")
     ⇒ "The CAT In The HAt"

Note that case conversion is not a one-to-one mapping of codepoints and length of the result may differ from length of the argument. Furthermore, because passing a character forces return type to be a character, functions are unable to perform proper substitution and result may differ compared to treating a one-character string. For example:

(upcase "ﬁ")  ; note: single character, ligature "fi"
     ⇒ "FI"

(upcase ?ﬁ)
     ⇒ 64257  ; i.e. ?ﬁ

To avoid this, a character must first be converted into a string, using string function, before being passed to one of the casing functions. Of course, no assumptions on the length of the result may be made.

Mapping for such special cases are taken from special-uppercase, special-lowercase and special-titlecase See section 文字のプロパティ.

文字列を比較する関数(caseの違いを無視するものや、オプションでcaseの違いを無視できるもの)については、文字および文字列の比較を参照されたい。

4.9 caseテーブル

特別なcaseテーブル(case table)をインストールすることにより、caseの変換をカスタマイズできます。caseテーブルは大文字と小文字の間のマッピングを指定します。caseテーブルはLispオブジェクトにたいするcase変換関数(前のセクションを参照)と、バッファー内のテキストに適用される関数の両方に影響します。それぞれのバッファーにはcaseテーブルがあります。新しいバッファーのcaseテーブルを初期化するために使用される、標準のcaseテーブル(standard case table)もあります。

caseテーブルは、サブタイプがcase-tableの文字テーブル(char-table。文字テーブルを参照)です。この文字テーブルはそれぞれの文字を対応する小文字にマップします。caseテーブルは、関連するテーブルを保持する3つの余分なスロットをもちます:

upcase: upcase(大文字)テーブルはそれぞれの文字を対応する大文字にマップする。
canonicalize: canonicalize(正準化)テーブルは、caseに関連する文字セットのすべてを、その文字セットの特別なメンバーにマップする。
equivalences: equivalence(同値)テーブルは、大の字小文字に関連した文字セットのそれぞれを、そのセットの次の文字にマップする。

単純な例では、小文字へのマッピングを指定することだけが必要です。3つの関連するテーブルは、このマッピングから自動的に計算されます。

大文字と小文字が1対1で対応しない言語もいくつかあります。これらの言語では、2つの異なる小文字が同じ大文字にマップされます。このような場合、大文字と小文字の両方にたいするマップを指定する必要があります。

追加のcanonicalizeテーブルは、それぞれの文字を正準化された等価文字にマップします。caseに関連する任意の2文字は、同じ正準等価文字(canonical equivalent character)をもちます。たとえば‘a’と‘A’はcase変換に関係があるので、これらの文字は同じ正準等価文字(両方の文字が‘a’、または両方の文字が‘A’)をもつべきです。

追加のequivalencesテーブルは、等価クラスの文字(同じ正準等価文字をもつ文字)それぞれを循環的にマップします(通常のASCIIでは、これは‘a’を‘A’に‘A’を‘a’にマップし、他の等価文字セットにたいしても同様にマップする)。

caseテーブルを構築する際は、canonicalizeにnilを指定できます。この場合、Emacsは大文字と小文字のマッピングでこのスロットを充填します。equivalencesにたいしてnilを指定することもできます。この場合、Emacsはcanonicalizeからこのスロットを充填します。実際に使用されるcaseテーブルでは、これらのコンポーネントは非nilです。canonicalizeを指定せずにequivalencesを指定しないでください。

以下はcaseテーブルに作用する関数です:

Function: case-table-p object: この述語は、objectが有効なcaseテーブルなら非nilをリターンする。

Function: set-standard-case-table table: この関数はtableを標準caseテーブルにして、これ以降に作成される任意のバッファーにたいしてこのテーブルが使用されるようにする。

Function: standard-case-table: これは標準caseテーブル(standard case table)をリターンする。

Function: current-case-table: この関数はカレントバッファーのcaseテーブルをリターンする。

Function: set-case-table table: これはカレントバッファーのcaseテーブルをtableにセットする。

Macro: with-case-table table body…: with-case-tableマクロはカレントcaseテーブルを保存してから、tableをカレントcaseテーブルにセットし、その後にbodyフォームを評価してから、最後にcaseテーブルをリストアします。リターン値は、bodyの最後のフォームの値です。throwかエラー(非ローカル脱出を参照)により異常終了した場合でも、caseテーブルはリストアされます。

ASCII文字のcase変換を変更する言語環境(language environment)がいくつかあります。たとえばトルコ語の言語環境では、ASCIIの大文字‘I’にたいする小文字は、トルコ語のドットがないi(‘ı’)です。これは(ASCIIベースのネットワークプロトコル実装のような)ASCIIの通常のcase変換を要求するコードに干渉する可能性があります。このような場合には、変数ascii-case-tableにたいしてwith-case-tableマクロを使用してください。これにより変更されていないASCII文字セットのcaseテーブルが保存されます。

Variable: ascii-case-table: ASCII文字セットにたいするcaseテーブル。すべての言語環境セッティングにおいて、これを変更するべきではない。

以下の3つの関数は、非ASCII文字セットを定義するパッケージにたいして便利なサブルーチンです。これらはcase-tableに指定されたcaseテーブルを変更します。これは標準構文テーブルも変更します。構文テーブルを参照してください。通常これらの関数は、標準caseテーブルを変更するために使用されます。

Function: set-case-syntax-pair uc lc case-table: この関数は対応する文字のペアー(一方は大文字でもう一方は小文字)を指定する。

Function: set-case-syntax-delims l r case-table: この関数は文字lとrを、case不変区切り(case-invariant delimiter)のマッチングペアーとする。

Function: set-case-syntax char syntax case-table: この関数はcharを構文syntaxのcase不変(case-invariant)とする。

Command: describe-buffer-case-table: このコマンドはカレントバッファーのcaseテーブルの内容にたいする説明を表示する。

5 リスト

リスト(list)は0個以上の要素(任意のLispオブジェクト)のシーケンスを表します。リストとベクターの重要な違いは、2つ以上のリストが構造の一部を共有できることです。加えて、リスト全体をコピーすることなく要素の挿入と削除ができます。

5.1 リストとコンスセル		コンスセルからリストが作られる方法。
5.2 リストのための述語		このオブジェクトはリストか? 2つのリストを比較する。
5.3 リスト要素へのアクセス		リストの一部を抽出する。
5.4 コンスセルおよびリストの構築		リスト構造の作成。
5.5 リスト変数の変更		変数に保存されたリストにたいする変更。
5.6 既存のリスト構造の変更		既存のリストに新しい要素を保存する。
5.7 集合としてのリストの使用		リストは有限な数学集合を表現できる。
5.8 連想リスト		リストは有限な関係またはマッピングを表現できる。
5.9 プロパティリスト		要素ペアのリスト。

5.1 リストとコンスセル

Lispでのリストは基本データ型ではありません。リストはコンスセル(cons cells)から構築されます(コンスセルとリスト型を参照)。コンスセルは順序つきペアを表現するデータオブジェクトです。つまりコンスセルは2つのスロットをもち、それぞれのスロットはLispオブジェクトを保持(holds)または参照(refers to)します。1つのスロットはCAR、もう1つはCDRです(これらの名前は歴史的なものである。コンスセルとリスト型を参照されたい)。CDRは“could-er(クダー)”と発音します。

わたしたちは、コンスセルのCARスロットに現在保持されているオブジェクトが何であれ、“このコンスセルのCARは、...”のような言い方をします。これはCDRの場合でも同様です。

リストとは互いに連なる(chained together)一連のコンスセルであり、各セルは次のセルを参照します。リストの各要素にたいして1つのコンスセルがあります。慣例によりコンスセルのCARはリストの要素を保持し、CDRはリストをチェーンするのに使用されます(CARとCDRの間の非対称性は完全に慣例的なものである。コンスセルのレベルではCARスロットとCDRスロットは同じようなプロパティーをもつ)。したがって、リスト内の各コンスセルのCDRスロットは次のコンスセルを参照します。

これも慣例的なものですが、リスト内の最後のコンスセルのCDRはnilです。わたしたちはこのようなnilで終端された構造を、真リスト(true list)と呼びます。Emacs Lispではシンボルnilはシンボルであり、かつ要素なしのリストでもあります。便宜上、シンボルnilはそのCDR(とCAR)にnilをもつと考えます。

したがって真リストのCDRは、常に真リストです。空でない真リストのCDRは、1番目の要素以外を含む真リストです。

リストの最後のコンスセルのCDRがnil以外の何らかの値の場合、このリストのプリント表現はドットペア表記(dotted pair notation。ドットペア表記を参照のこと)を使用するので、わたしたちはこの構造をドットリスト(dotted list)と呼びます。他の可能性もあります。あるコンスセルのCDRが、そのリストのそれより前にある要素を指すかもしれません。わたしたちは、この構造を循環リスト(circular list)と呼びます。

ある目的においてはそのリストが真リストか、循環リストなのか、ドットリストなのかが問題にならない場合もあります。そのプログラムがリストを充分に辿って最後のコンスセルのCDRを確認しようとしないなら、これは問題になりません。しかしリストを処理する関数のいくつかは真リストを要求し、ドットリストの場合はエラーをシグナルします。リストの最後を探そうと試みる関数のほとんどは、循環リストを与えると無限ループに突入します。

ほとんどのコンスセルはリストの一部として使用されるので、わたしたちはコンスセルで構成される任意の構造をリスト構造(list structure)と呼びます。

5.2 リストのための述語

以下の述語はあるLispオブジェクトがアトムか、コンスセルか、リストなのか、またはオブジェクトがnilかどうかテストします(これらの述語の多くは他の述語で定義することもできるが、多用されるので個別に定義する価値がある)。

Function: consp object: この関数はobjectがコンスセルならt、それ以外はnilをリターンする。たとえnilがリストであっても、コンスセルではない。

Function: atom object

この関数はobjectがアトムならt、それ以外はnilをリターンする。シンボルnilはアトムであり、かつリストでもある。そのようなLispオブジェクトはnilだけである。

(atom object) ≡ (not (consp object))

Function: listp object

この関数はobjectがコンスセルかnilならt、それ以外はnilをリターンする。

(listp '(1))
     ⇒ t

(listp '())
     ⇒ t

Function: nlistp object

この関数はlistpの反対である。objectがリストでなければt、それ以外はnilをリターンする。

(listp object) ≡ (not (nlistp object))

Function: null object

この関数はobjectがnilならt、それ以外はnilをリターンする。この関数はnotと等価だが、明解にするためにobjectをリストだと考えるときはnull、真偽値だと考えるときはnotを使用すること(条件の組み合わせのnotを参照)。

(null '(1))
     ⇒ nil

(null '())
     ⇒ t

5.3 リスト要素へのアクセス

Function: car cons-cell

この関数はコンスセルcons-cellの1番目のスロットが参照する値をリターンする。言い換えるとこの関数はcons-cellのCARをリターンする。

特別なケースとしてcons-cellがnilの場合、この関数はnilをリターンする。したがってリストはすべて引数として有効である。引数がコンスセルでもnilでもなければエラーがシグナルされる。

(car '(a b c))
     ⇒ a

(car '())
     ⇒ nil

Function: cdr cons-cell

この関数はコンスセルcons-cellの2番目のスロットにより参照される値をリターンする。言い換えるとこの関数はcons-cellのCDRをリターンする。

特別なケースとしてcons-cellがnilの場合、この関数はnilをリターンする。したがってリストはすべて引数として有効である。引数がコンスセルでもnilでもければエラーがシグナルされる。

(cdr '(a b c))
     ⇒ (b c)

(cdr '())
     ⇒ nil

Function: car-safe object

この関数により他のデータ型によるエラーを起こさずに、コンスセルのCARを取得できり。この関数はobjectがコンスセルならobjectのCAR、それ以外はnilをリターンする。この関数は、objectがリストでなければエラーをシグナルするcarとは対象的である。

(car-safe object)
≡
(let ((x object))
  (if (consp x)
      (car x)
    nil))

Function: cdr-safe object

この関数により他のデータ型によるエラーを起こさずに、コンスセルのCDRを取得できる。この関数はobjectがコンスセルならobjectのCDR、それ以外はnilをリターンする。この関数は、objectがリストでないときはエラーをシグナルするcdrとは対象的である。

(cdr-safe object)
≡
(let ((x object))
  (if (consp x)
      (cdr x)
    nil))

Macro: pop listname

このマクロはリストのCARを調べて、それをリストから取り去るのを一度に行なう便利な方法を提供する。この関数はlistnameに格納されたリストにたいして処理を行なう。この関数はリストから1番目の要素を削除して、CDRをlistnameに保存し、その後で削除した要素をリターンする。

もっとも単純なケースは、リストに名前をつけるためのクォートされていないシンボルの場合である。この場合、このマクロは(prog1 (car listname) (setq listname (cdr listname)))と等価である。

x
     ⇒ (a b c)
(pop x)
     ⇒ a
x
     ⇒ (b c)

より一般的なのはlistnameが汎変数(generalized variable)の場合である。この場合、このマクロはsetfを使用してlistnameに保存する。ジェネリック変数を参照のこと。

リストに要素を追加するpushマクロについてはリスト変数の変更を参照のこと。

Function: nth n list

この関数はlistのn番目の要素をリターンする。要素は0から数えられるのでlistのCARは要素0になる。listの長さがn以下なら値はnil。

(nth 2 '(1 2 3 4))
     ⇒ 3

(nth 10 '(1 2 3 4))
     ⇒ nil

(nth n x) ≡ (car (nthcdr n x))

これは関数eltも類似しているが、任意の種類のシーケンスに適用される。歴史的な理由によりこの関数は逆の順序で引数を受け取る。シーケンスを参照のこと。

Function: nthcdr n list

この関数はlistのn番目のCDRをリターンする。言い換えると、この関数はlistの最初のn個のリンクをスキップしてから、それ以降をリターンする。

nが0ならnthcdrはlist全体をリターンする。listの長さがn以下ならnthcdrはnilをリターンする。

(nthcdr 1 '(1 2 3 4))
     ⇒ (2 3 4)

(nthcdr 10 '(1 2 3 4))
     ⇒ nil

(nthcdr 0 '(1 2 3 4))
     ⇒ (1 2 3 4)

Function: last list &optional n: この関数はlistの最後のリンクをリターンする。このリンクのcarはこのリストの最後の要素。listがnullならnilがリターンされる。nが非nilならn番目から最後までのリンクがリターンされる。nがlistの長さより大きければlist全体がリターンされる。

Function: safe-length list

この関数はエラーや無限ループの危険なしで、listの長さをリターンする。この関数は一般的に、リスト内のコンスセルの個数をリターンする。しかし循環リストでは単に上限値が値となるため、非常に大きくなる場合があります。

listがnil]とコンスセルのいずれでもなければsafe-lengthは0をリターンする。

循環リストを考慮しなくてもよい場合にリストの長さを計算するもっとも一般的な方法は、lengthを使う方法です。シーケンスを参照してください。

Function: caar cons-cell: これは(car (car cons-cell))と同じ。

Function: cadr cons-cell: これは(car (cdr cons-cell))か(nth 1 cons-cell)と同じ。

Function: cdar cons-cell: これは(cdr (car cons-cell))と同じ。

Function: cddr cons-cell: これは(cdr (cdr cons-cell))か(nthcdr 2 cons-cell)と同じ。

In addition to the above, 24 additional compositions of car and cdr are defined as cxxxr and cxxxxr, where each x is either a or d. cadr, caddr, and cadddr pick out the second, third or fourth elements of a list, respectively. cl-lib provides the same under the names cl-second, cl-third, and cl-fourth. See List Functions in Common Lisp Extensions.

Function: butlast x &optional n: この関数はリストxから、最後の要素か最後のn個の要素を削除してリターンする。nが0より大きければこの関数はリストのコピーを作成するので、元のリストに影響はない。一般的に(append (butlast x n) (last x n))は、xと等しいリストをリターンする。

Function: nbutlast x &optional n: この関数はリストのコピーを作成するのではなく、cdrを適切な要素に変更することにより破壊的に機能するバージョンのbutlastである。

5.4 コンスセルおよびリストの構築

リストはLispの中核にあたる機能なので、リストを構築するために多くの関数があります。consはリストを構築する基本的な関数です。しかしEmacsのソースコードでは、consよりlistのほうが多く使用されているのは興味深いことです。

Function: cons object1 object2

この関数は新しいリスト構造を構築するための、もっとも基本的な関数である。この関数はobject1をCAR、object2をCDRとする新しいコンスセルを作成して、それから新しいコンスセルをリターンする。引数object1とobject2には任意のLispオブジェクトを指定できるが、ほとんどの場合object2はリストである。

(cons 1 '(2))
     ⇒ (1 2)

(cons 1 '())
     ⇒ (1)

(cons 1 2)
     ⇒ (1 . 2)

リストの先頭に1つの要素を追加するために、consがよく使用される。これをリストに要素をコンスすると言います。²たとえば:

(setq list (cons newelt list))

この例で使用されているlistという名前の変数と、以下で説明するlistという名前の関数は競合しないことに注意されたい。すべてのシンボルが、変数ト関数の両方の役割を果たすことができる。

Function: list &rest objects

この関数はobjectsを要素とするリストを作成する。結果となるリストは常にnil終端される。objectsを指定しないと空リストがリターンされる。

(list 1 2 3 4 5)
     ⇒ (1 2 3 4 5)

(list 1 2 '(3 4 5) 'foo)
     ⇒ (1 2 (3 4 5) foo)

(list)
     ⇒ nil

Function: make-list length object

この関数は各要素がobjectであるような、length個の要素からなるリストを作成する。make-listとmake-string(文字列の作成を参照)を比較してみよ。

(make-list 3 'pigs)
     ⇒ (pigs pigs pigs)

(make-list 0 'pigs)
     ⇒ nil

(setq l (make-list 3 '(a b)))
     ⇒ ((a b) (a b) (a b))
(eq (car l) (cadr l))
     ⇒ t

Function: append &rest sequences

この関数はsequencesのすべての要素を含むリストをreturnします。sequencesにはリスト、ベクター、ブールベクター、文字列も指定できるが、通常は最後にリストを指定すること。最後の引数を除くすべての引数はコピーされるので、変更される引数はない(コピーを行なわずにリストを結合する方法についてはリストを再配置する関数のnconcを参照のこと)。

より一般的にはappendにたいする最後の引数は、任意のLispオブジェクトを指定できる。最後の引数はコピーや変換はされない。最後の引数は、新しいリストの最後のコンスセルのCDRとなる。最後の引数もリストならば、このリストの要素は実質的には結果リストの要素になる。最後の要素がリストでなければ、最後のCDRが(真リストで要求される)nilではないので、結果はドットリストになる。

以下はappendを使用した例です:

(setq trees '(pine oak))
     ⇒ (pine oak)
(setq more-trees (append '(maple birch) trees))
     ⇒ (maple birch pine oak)

trees
     ⇒ (pine oak)
more-trees
     ⇒ (maple birch pine oak)

(eq trees (cdr (cdr more-trees)))
     ⇒ t

appendがどのように機能するか、ボックスダイアグラムで確認できます。変数treesはリスト(pine oak)にセットされ、それから変数more-treesにリスト(maple birch pine oak)がセットされます。しかし変数treesは継続して元のリストを参照します:

more-trees                trees
|                           |
|     --- ---      --- ---   -> --- ---      --- ---
 --> |   |   |--> |   |   |--> |   |   |--> |   |   |--> nil
      --- ---      --- ---      --- ---      --- ---
       |            |            |            |
       |            |            |            |
        --> maple    -->birch     --> pine     --> oak

空のシーケンスはappendによりリターンされる値に寄与しません。この結果、最後の引数にnilを指定すると、それより前の引数のコピーを強制することになります。

trees
     ⇒ (pine oak)

(setq wood (append trees nil))
     ⇒ (pine oak)

wood
     ⇒ (pine oak)

(eq wood trees)
     ⇒ nil

関数copy-sequenceが導入される以前は,これがリストをコピーする通常の方法でした。シーケンス、配列、ベクターを参照してください。

以下はappendの引数としてベクターと文字列を使用する例です:

(append [a b] "cd" nil)
     ⇒ (a b 99 100)

apply (関数の呼び出しを参照)の助けを借りることにより、リストのリストの中のすべてのリストをappendできます。

(apply 'append '((a b c) nil (x y z) nil))
     ⇒ (a b c x y z)

sequencesが与えられなければnilがリターンされます:

(append)
     ⇒ nil

以下は最後の引数がリストでない場合の例です:

(append '(x y) 'z)
     ⇒ (x y . z)
(append '(x y) [z])
     ⇒ (x y . [z])

2番目の例は最後の引数はリストではないシーケンスの場合で、このシーケンスの要素は、結果リストの要素にはなりません。かわりに最後の引数がリストでないときと同様、シーケンスが最後のCDRになります。

Function: copy-tree tree &optional vecp

この関数はツリーtreeのコピーをリターンする。treeがコンスセルなら、同じCARとCDRをもつ新しいコンスセルを作成してから、同じ方法によりCARとCDRを再帰的にコピーする。

treeがコンスセル以外の場合、通常はcopy-treeは単にtreeをリターンする。しかしvecpが非nilなら、この関数はベクターでもコピーします(そしてベクターの要素を再帰的に処理する)。

Function: number-sequence from &optional to separation

これはfromからseparationづつインクリメントして、toの直前で終わる、数字のリストをリターンする。separationには正か負の数を指定でき、デフォルトは1。toがnil、または数値的にfromと等しければ、値は1要素のリスト(from)になる。separationが正でtoがfromより小さい、またはseparationが負でtoがfromより大きければ、これらの引数は空のシーケンスを指示することになるので、値はnilになります。

separationが0で、toがnilでもなく、数値的にfromとも等しくまければ、これらの引数は無限シーケンスを指示することになるので、エラーがシグナルされる。

引数はすべて数字である。浮動少数点数の計算は正確ではないので、浮動少数点数の引数には注意する必要がある。たとえばマシンへの依存により、(number-sequence 0.4 0.8 0.2)が3要素のリストをリターンして、(number-sequence 0.4 0.6 0.2)が1要素のリスト(0.4)をリターンnすることがよく起こる。リストのn番目の要素は、厳密に(+ from (* n separation))という式により計算される。リストに確実にtoが含まれるようにするために、この式に適切な型のtoを渡すことができる。別の方法としてtoを少しだけ大きな値(separationが負なら少しだけ小さな値)に置き換えることもできる。

例をいくつか示す:

(number-sequence 4 9)
     ⇒ (4 5 6 7 8 9)
(number-sequence 9 4 -1)
     ⇒ (9 8 7 6 5 4)
(number-sequence 9 4 -2)
     ⇒ (9 7 5)
(number-sequence 8)
     ⇒ (8)
(number-sequence 8 5)
     ⇒ nil
(number-sequence 5 8 -1)
     ⇒ nil
(number-sequence 1.5 6 2)
     ⇒ (1.5 3.5 5.5)

5.5 リスト変数の変更

以下の関数と1つのマクロは、変数に格納されたリストを変更する便利な方法を提供します。

Macro: push element listname

このマクロはCARがelementで、CDRがlistnameのリストであるような新しいリストを作成して、そのリストをlistnameに保存する。listnameがリストに名前をつけるクォートされていないシンボルのときは単純で、この場合マクロは(setq listname (cons element listname))と等価になる。

(setq l '(a b))
     ⇒ (a b)
(push 'c l)
     ⇒ (c a b)
l
     ⇒ (c a b)

より一般的なのはlistnameが汎変数の場合である。この場合、このマクロは(setf listname (cons element listname))と等価になる。ジェネリック変数を参照のこと。

リストから1番目の要素を取り出すpopマクロについては、リスト要素へのアクセスを参照されたい。

以下の2つの関数は、変数の値であるリストを変更します。

Function: add-to-list symbol element &optional append compare-fn

この関数はelementがsymbolの値のメンバーでなければ、symbolにelementをコンスすることにより、変数symbolをセットする。この関数はリストが更新されているか否かに関わらず、結果のリストをリターンする。symbolの値は呼び出し前にすでにリストであることが望ましい。elementがリストの既存メンバーか比較するために、add-to-listはcompare-fnを使用する。compare-fnがnilならequalを使用する。

elementが追加される場合は、通常はsymbolの前に追加されるが、オプションの引数appendが非nilなら最後に追加される。

引数symbolは暗黙にクォートされない。setqとは異なりadd-to-listはsetのような通常の関数である。クォートしたい場合には自分で引数をクォートすること。

以下にadd-to-listを使用する方法をシナリオで示します:

(setq foo '(a b))
     ⇒ (a b)

(add-to-list 'foo 'c)     ;; cを追加
     ⇒ (c a b)

(add-to-list 'foo 'b)     ;; 効果なし
     ⇒ (c a b)

foo                       ;; fooが変更された
     ⇒ (c a b)

以下は(add-to-list 'var value)と等価な式です:

(or (member value var)
    (setq var (cons value var)))

Function: add-to-ordered-list symbol element &optional order

この関数は古い値のorder (リストであること)で指定された位置に、elementを挿入して変数symbolをセットする。elementがすでにこのリストのメンバなら、リスト内の要素の位置はorderにしたがって調整される。メンバーか否かはeqを使用してテストされる。この関数は更新されているかどうかに関わらず、結果のリストをリターンする。

orderは通常は数字(整数か浮動小数点数)で、リストの要素はその数字の昇順で並べられる。

orderは省略またはnilを指定できる。これによりリストにelementがすでに存在するなら、elementの数字順序は変更されない。それ以外ならelementは数字順序をもたない。リストの数字順序をもたない要素はリストの最後に配置され、特別な順序はつかない。

orderに他の値を指定すると、elementがすでに数字順序をもつときは数字順序が削除される。それ以外はならnilと同じ。

引数symbolは暗黙にクォートされない。add-to-ordered-listはsetqなどとは異なり、setのような通常の関数である。必要なら引数を自分でクォートすること。

順序の情報はsymbolのlist-orderプロパティーにハッシュテーブルで保存される。

以下にadd-to-ordered-listを使用する方法をシナリオで示します:

(setq foo '())
     ⇒ nil

(add-to-ordered-list 'foo 'a 1)     ;; aを追加
     ⇒ (a)

(add-to-ordered-list 'foo 'c 3)     ;; cを追加
     ⇒ (a c)

(add-to-ordered-list 'foo 'b 2)     ;; bを追加
     ⇒ (a b c)

(add-to-ordered-list 'foo 'b 4)     ;; bを移動
     ⇒ (a c b)

(add-to-ordered-list 'foo 'd)       ;; dを後に追加
     ⇒ (a c b d)

(add-to-ordered-list 'foo 'e)       ;; eを追加
     ⇒ (a c b e d)

foo                       ;; fooが変更された
     ⇒ (a c b e d)

5.6 既存のリスト構造の変更

プリミティブ関数setcarとsetcdrにより、コンスセルのCARおよびCDRの内容を変更できます。わたしたちは、これらは既存のリスト構造を変更するので、これらを破壊的処理です。

Common Lispに関する注意: Common Lispはリスト構造の変更にrplacaとrplacdを使用する。これらはsetcarやsetcdrと同じ方法でリスト構造を変更するが、setcarとsetcdrは新しいCARやCDRをリターンするのにたいして、Common Lispの関数はコンスセルをリターンする。

5.6.1 `setcar`によるリスト要素の変更

コンスセルのCARの変更はsetcarで行ないます。リストにたいして使用するとsetcarはリストの1つの要素を別の要素に置き換えます。

Function: setcar cons object

この関数は以前のCARを置き換えて、consの新しいCARにobjectを格納する。言い換えると、この関数はconsのCARスロットをobjectを参照するように変更する。この関数は値objectをリターンする。たとえば:

(setq x '(1 2))
     ⇒ (1 2)

(setcar x 4)
     ⇒ 4

x
     ⇒ (4 2)

コンスセルが複数のリストを共有する構造の一部なら、コンスに新しいCARを格納することにより、これら共有されたリストの各1つの要素を変更します。以下は例です:

;; 部分的に共有された2つのリストを作成
(setq x1 '(a b c))
     ⇒ (a b c)
(setq x2 (cons 'z (cdr x1)))
     ⇒ (z b c)

;; 共有されたリンクのCARを置き換え
(setcar (cdr x1) 'foo)
     ⇒ foo
x1                           ; 両方のリストが変更された
     ⇒ (a foo c)
x2
     ⇒ (z foo c)

;; 共有されていないリンクのCARを置き換え
(setcar x1 'baz)
     ⇒ baz
x1                           ; 1つのリストだけが変更された
     ⇒ (baz foo c)
x2
     ⇒ (z foo c)

なぜbを置き換えると両方が変更されるのかを説明するために、変数x1とx2の2つのリストによる共有構造を視覚化してみましょう:

        --- ---        --- ---      --- ---
x1---> |   |   |----> |   |   |--> |   |   |--> nil
        --- ---        --- ---      --- ---
         |        -->   |            |
         |       |      |            |
          --> a  |       --> b        --> c
                 |
       --- ---   |
x2--> |   |   |--
       --- ---
        |
        |
         --> z

同じ関係を別のボックス図で示すと、以下のようになります:

x1:
 --------------       --------------       --------------
| car   | cdr  |     | car   | cdr  |     | car   | cdr  |
|   a   |   o------->|   b   |   o------->|   c   |  nil |
|       |      |  -->|       |      |     |       |      |
 --------------  |    --------------       --------------
                 |
x2:              |
 --------------  |
| car   | cdr  | |
|   z   |   o----
|       |      |
 --------------

5.6.2 リストのCDRの変更

CDRを変更するもっとも低レベルのプリミティブ関数はsetcdrです:

Function: setcdr cons object: この関数は前のCDRを置き換えて、consの新しいCDRにobjectを格納する。言い換えると、この関数はconsのCDRがobjectを参照するように変更する。この関数は値objectをリターンする。

以下はリストのCDRを、他のリストに置き換える例です。1番目の要素以外のすべての要素は、別のシーケンスまたは要素のために取り除かれます。1番目の要素はリストのCARなので変更されず、CDRを通じて到達することもできないからです。

(setq x '(1 2 3))
     ⇒ (1 2 3)

(setcdr x '(4))
     ⇒ (4)

x
     ⇒ (1 4)

リスト内のコンスセルのCDRを変更することにより、リストの途中から要素を削除できます。たとえば以下では、1番目のコンスセルのCDRを変更することにより、2番目の要素bをリスト(a b c)から削除します。

(setq x1 '(a b c))
     ⇒ (a b c)
(setcdr x1 (cdr (cdr x1)))
     ⇒ (c)
x1
     ⇒ (a c)

以下に結果をボックス表記で示します:

                   --------------------
                  |                    |
 --------------   |   --------------   |    --------------
| car   | cdr  |  |  | car   | cdr  |   -->| car   | cdr  |
|   a   |   o-----   |   b   |   o-------->|   c   |  nil |
|       |      |     |       |      |      |       |      |
 --------------       --------------        --------------

以前は要素bを保持していた2番目のコンスセルは依然として存在し、そのCARもbのままですが、すでにこのリストの一部を形成していません。

CDRを変更して新しい要素を挿入するのも同じくらい簡単です:

(setq x1 '(a b c))
     ⇒ (a b c)
(setcdr x1 (cons 'd (cdr x1)))
     ⇒ (d b c)
x1
     ⇒ (a d b c)

以下に結果をボックス表記で示します:

 --------------        -------------       -------------
| car  | cdr   |      | car  | cdr  |     | car  | cdr  |
|   a  |   o   |   -->|   b  |   o------->|   c  |  nil |
|      |   |   |  |   |      |      |     |      |      |
 --------- | --   |    -------------       -------------
           |      |
     -----         --------
    |                      |
    |    ---------------   |
    |   | car   | cdr   |  |
     -->|   d   |   o------
        |       |       |
         ---------------

5.6.3 リストを再配置する関数

以下ではリストの構成要素であるコンスセルのCDRを変更することにより、リストを破壊的に再配置する関数をいくつか示します。これらの関数が破壊的だという理由は、これらの関数が引数として渡された元のリストを処理してリターン値となる新しいリストを形成するために、リストのコンスセルを再リンクするからです。

コンスセルを変更する他の関数については、集合としてのリストの使用のdelqを参照してください。

Function: nconc &rest lists

この関数はlistsの要素すべてを含むリストをリターンする。append (コンスセルおよびリストの構築を参照)とは異なり、listsはコピーされない。かわりにlistsの各リストの最後のCDRが次のリストを参照するように変更される。listsの最後のリストは変更されない。たとえば:

(setq x '(1 2 3))
     ⇒ (1 2 3)

(nconc x '(4 5))
     ⇒ (1 2 3 4 5)

x
     ⇒ (1 2 3 4 5)

nconcの最後の引数は変更されないので、上記の例のように'(4 5)のような定数リストを使用するのが合理的である。また同じ理由により最後の引数がリストである必要はない。

(setq x '(1 2 3))
     ⇒ (1 2 3)

(nconc x 'z)
     ⇒ (1 2 3 . z)

x
     ⇒ (1 2 3 . z)

しかし他の(最後を除くすべての)引数はリストでなければなければならない。

一般的な落とし穴としては、nconcにたいしてクォートされたリスト定数を最後以外の引数として使用した場合である。これを行なうと、実行するごとにプログラムはリスト定数を変更するだろう! 何が起こるのかを以下に示す:

(defun add-foo (x)            ; この関数ではfoo
  (nconc '(foo) x))           ;   を引数の前に追加したい

(symbol-function 'add-foo)
     ⇒ (lambda (x) (nconc (quote (foo)) x))

(setq xx (add-foo '(1 2)))    ; 動いているように見える
     ⇒ (foo 1 2)

(setq xy (add-foo '(3 4)))    ; 何が起きているのか?
     ⇒ (foo 1 2 3 4)

(eq xx xy)
     ⇒ t

(symbol-function 'add-foo)
     ⇒ (lambda (x) (nconc (quote (foo 1 2 3 4) x)))

5.7 集合としてのリストの使用

リストは順序なしの数学的集合 — リスト内に要素があれば集合の要素の値としてリスト内の順序は無視される — を表すことができます。2つの集合を結合(union)するには、(重複する要素を気にしなければ)appendを使用します。equalである重複を取り除くにはdelete-dupsを使用します。集合にたいする他の有用な関数にはmemqやdelqや、それらのequalバージョンであるmemberとdeleteが含まれます。

Common Lispに関する注意: 集合を処理するためにCommon Lispには(要素の重複がない)関数unionがある。これらの関数は標準のGNU Emacs Lispには存在しないが、cl-libがこれらを提供する。Lists as Sets in Common Lisp Extensionsを参照されたい。

Function: memq object list

この関数はobjectがlistのメンバーかどうかをテストする。メンバーならmemqは、objectで最初に見つかった要素から開始されるリストをリターンする。メンバーでなければnilをリターンする。memqの文字‘q’は、この関数がobjectとリスト内の要素の比較にeqを使用することを示す。たとえば:

(memq 'b '(a b c b a))
     ⇒ (b c b a)

(memq '(2) '((1) (2)))    ; (2)と(2)はeqではない。
     ⇒ nil

Function: delq object list

この関数はlistからobjectとeqであるような、すべての要素を破壊的に取り除いて結果のリストをリターンする。delqの文字‘q’は、この関数がobjectとリスト内の要素の比較にeqを使用することを示す(memqやremqと同様)。

delqを呼び出すときは、通常は元のリストを保持していた変数にリターン値を割り当てて使用する必要がある(理由は以下参照)。

delq関数がリストの先頭にある要素を削除する場合は、単にリストを読み進めてこの要素の後から開始される部分リストをリターンします。つまり:

(delq 'a '(a b c)) ≡ (cdr '(a b c))

リストの途中にある要素を削除するときは、必要なCDR (リストのCDRの変更を参照)を変更することで削除を行います。

(setq sample-list '(a b c (4)))
     ⇒ (a b c (4))

(delq 'a sample-list)
     ⇒ (b c (4))

sample-list
     ⇒ (a b c (4))

(delq 'c sample-list)
     ⇒ (a b (4))

sample-list
     ⇒ (a b (4))

(delq 'a sample-list)は何も取り除きませんが(単に短いリストをリターンする)、(delq 'c sample-list)は3番目の要素を取り除いてsample-listを変更することに注意してください。引数listを保持するように形成された変数が、実行後にもっと少ない要素になるとか、元のリストを保持すると仮定しないでください! かわりにdelqの結果を保存して、それを使用してください。元のリストを保持していた変数に結果を書き戻すことはよく行なわれます。

(setq flowers (delq 'rose flowers))

以下の例では、delqが比較しようとしている(4)と、sample-list内の(4)はeqではありません:

(delq '(4) sample-list)
     ⇒ (a c (4))

与えられた値とequalな要素を削除したい場合には、delete (以下参照)を使用してください。

Function: remq object list

この関数はobjectとeqなすべての要素が除かれた、listのコピーをリターンする。remqの文字‘q’は、この関数がobjectとリスト内の要素の比較にeqを使用することを示す。

(setq sample-list '(a b c a b c))
     ⇒ (a b c a b c)

(remq 'a sample-list)
     ⇒ (b c b c)

sample-list
     ⇒ (a b c a b c)

Function: memql object list

関数memqlはeql(浮動少数点数の要素は値で比較される)を使用してメンバーとeqlを比較することにより、objectがlistのメンバーかどうかをテストする。objectがメンバーなら、memqlはlist内で最初に見つかった要素から始まるリスト、それ以外ならnilをリターンする。

memqと比較してみよう:

(memql 1.2 '(1.1 1.2 1.3))  ; 1.2と1.2はeql。
     ⇒ (1.2 1.3)

(memq 1.2 '(1.1 1.2 1.3))  ; 1.2と1.2はeqではない。
     ⇒ nil

以下の3つの関数はmemq、delq、remqと似ていますが、要素の比較にeqではなくequalを使用します。同等性のための述語を参照してください。

Function: member object list

関数memberは、メンバーとobjectをequalを使用して比較して、objectがlistのメンバーかどうかをテストする。objectがメンバーなら、memberはlistで最初に見つかったところから開始されるリスト、それ以外ならnilをリターンする。

memqと比較してみよう:

(member '(2) '((1) (2)))  ; (2) and (2) are equal.
     ⇒ ((2))

(memq '(2) '((1) (2)))    ; (2)と(2)はeqではない。
     ⇒ nil

;; 同じ内容の2つの文字列はequal
(member "foo" '("foo" "bar"))
     ⇒ ("foo" "bar")

Function: delete object sequence

この関数はsequenceからobjectとequalな要素を取り除いて、結果のシーケンスをリターンする。

sequenceがリストなら、deleteがdelqに対応するように、memberはmemqに対応する。つまりこの関数はmemberと同様、要素とobjectの比較にequalを使用する。マッチする要素が見つかったら、delqが行なうようにその要素を取り除く。delqと同様、通常は元のリストを保持していた変数にリターン値を割り当てて使用する。

sequenceがベクターか文字列なら、deleteはobjectとequalなすべての要素を取り除いたsequenceのコピーをリターンする。

たとえば:

(setq l '((2) (1) (2)))
(delete '(2) l)
     ⇒ ((1))
l
     ⇒ ((2) (1))
;; lの変更に信頼性を要するときは
;; (setq l (delete '(2) l))と記述する。

(setq l '((2) (1) (2)))
(delete '(1) l)
     ⇒ ((2) (2))
l
     ⇒ ((2) (2))
;; このケースではlのセットの有無に違い
;; はないが他のケースに倣ってセットするべき

(delete '(2) [(2) (1) (2)])
     ⇒ [(1)]

Function: remove object sequence

この関数はdeleteに対応する非破壊的な関数である。この関数はobjectとequalな要素を取り除いた、sequence(リスト、ベクター、文字列)のコピーをリターンする。たとえば:

(remove '(2) '((2) (1) (2)))
     ⇒ ((1))

(remove '(2) [(2) (1) (2)])
     ⇒ [(1)]

Common Lispに関する注意: GNU Emacs Lispの関数member、delete、removeはCommon Lispではなく、Maclispを継承する。Common Lispでは比較にequalを使用しない。

Function: member-ignore-case object list: この関数はmemberと同様だが、objectが文字列でcaseとテキスト表現の違いを無視する。文字の大文字と小文字は等しいものとして扱われ、比較に先立ちユニバイト文字列はマルチバイト文字列に変換される。

Function: delete-dups list: この関数はlistからすべてのequalな重複を破壊的に取り除いて、結果をlistに保管してそれをリターンする。list内の要素にequalな要素がいくつかあるなら、delete-dupsは最初の要素を残す。

変数に格納されたリストへの要素の追加や、それを集合として使用する方法については、リスト変数の変更の関数add-to-listも参照してください。

5.8 連想リスト

連想配列(association list、短くはalist)は、キーと値のマッピングを記録します。これは連想(associations)と呼ばれるコンスセルのリストです。各コンスセルにおいてCARはキー(key)で、CDRは連想値(associated value)となります。³

以下はalistの例です。キーpineは値cones、キーoakはacorns、キーmapleはseedsに関連付けられます。

((pine . cones)
 (oak . acorns)
 (maple . seeds))

alist内の値とキーには、任意のLispオブジェクトを指定できます。たとえば以下のalist0では、シンボルaは数字1、文字列"b"はリスト(2 3)(alist要素のCDR)に関連付けられます。

((a . 1) ("b" 2 3))

要素のCDRのCARに連想値を格納するようにalistデザインするほうがよい場合があります。以下はそのようなalistです。

((rose red) (lily white) (buttercup yellow))

この例では、redがroseに関連付けられる値だと考えます。この種のalistの利点は、CDRのCDRの中に他の関連する情報 — 他のアイテムのリストでさえも — を格納することができることです。不利な点は、与えられた値を含む要素を見つけるためにrassq(以下参照)を使用できないことです。これらを検討することが重要でない場合には、すべての与えられたalistにたいして一貫している限り、選択は好みの問題といえます。

上記で示したのと同じalistは、要素のCDRに連想値をもつと考えることができます。この場合、roseに関連付けられる値はリスト(red)になるでしょう。

連想リストは新しい連想値を簡単にリストの先頭に追加できるので、スタックに保持したいような情報を記録するのによく使用されます。連想リストから与えられたキーにたいして連想値を検索する場合、それが複数ある場合は、最初に見つかったものがreturnされます。

Emacs Lispでは、連想リストがコンスセルでなくても、それはエラーではありません。alist検索関数は、単にそのような要素を無視します。多くの他のバージョンのLispでは、このような場合はエラーをシグナルします。

いくつかの観点において、プロパティーリストは連想リストと似ていることに注意してください。それぞれのキーが一度だけ出現するような場合、プロパティーリストは連想リストと同様に振る舞います。プロパティーリストと連想リストの比較については、プロパティリストを参照してください。

Function: assoc key alist &optional testfn

This function returns the first association for key in alist, comparing key against the alist elements using testfn if it is non-nil and equal otherwise (see section 同等性のための述語). It returns nil if no association in alist has a CAR equal to key. For example:

(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     ⇒ ((pine . cones) (oak . acorns) (maple . seeds))
(assoc 'oak trees)
     ⇒ (oak . acorns)
(cdr (assoc 'oak trees))
     ⇒ acorns
(assoc 'birch trees)
     ⇒ nil

以下はキーと値がシンボルでない場合の例である:

(setq needles-per-cluster
      '((2 "Austrian Pine" "Red Pine")
        (3 "Pitch Pine")
        (5 "White Pine")))

(cdr (assoc 3 needles-per-cluster))
     ⇒ ("Pitch Pine")
(cdr (assoc 2 needles-per-cluster))
     ⇒ ("Austrian Pine" "Red Pine")

関数assoc-stringはassocと似ていますが、文字列間の特定の違いを無視する点が異なります。文字および文字列の比較を参照してください。

Function: rassoc value alist

この関数はalistの中から値valueをもつ最初の連想をリターンする。CDRがvalueとequalであるような連想値がalistになければ、この関数はnilをリターンする。

rassocはassocと似てイルが、CARではなくalistの連想値のCDRを比較する。この関数は与えられた値に対応するキーを探す、assocの逆バージョンと考えることができよう。

Function: assq key alist

This function is like assoc in that it returns the first association for key in alist, but it makes the comparison using eq. assq returns nil if no association in alist has a CAR eq to key. This function is used more often than assoc, since eq is faster than equal and most alists use symbols as keys. See section 同等性のための述語.

(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))
     ⇒ ((pine . cones) (oak . acorns) (maple . seeds))
(assq 'pine trees)
     ⇒ (pine . cones)

逆にキーがシンボルではないalistでは、通常はassqは有用ではない:

(setq leaves
      '(("simple leaves" . oak)
        ("compound leaves" . horsechestnut)))

(assq "simple leaves" leaves)
     ⇒ nil
(assoc "simple leaves" leaves)
     ⇒ ("simple leaves" . oak)

Function: alist-get key alist &optional default remove testfn

This function is similar to assq. It finds the first association (key . value) by comparing key with alist elements, and, if found, returns the value of that association. If no association is found, the function returns default. Comparison of key against alist elements uses the function specified by testfn, defaulting to eq.

This is a generalized variable (see section ジェネリック変数) that can be used to change a value with setf. When using it to set a value, optional argument remove non-nil means to remove key’s association from alist if the new value is eql to default.

Function: rassq value alist

この関数は、alist内から値valueをもつ最初の連想値をリターンする。alist内にCDRがvalueとeqであるような連想値が存在しないならnilをリターンする。

rassqはassqと似ていますが、CARではなくalistの各連想のCDRを比較します。この関数を、与えられた値に対応するキーを探すassqの逆バージョンと考えることができます。

たとえば:

(setq trees '((pine . cones) (oak . acorns) (maple . seeds)))

(rassq 'acorns trees)
     ⇒ (oak . acorns)
(rassq 'spores trees)
     ⇒ nil

rassqは要素のCDRのCARに保管された値の検索はできません:

(setq colors '((rose red) (lily white) (buttercup yellow)))

(rassq 'white colors)
     ⇒ nil

この場合、連想(lily white)のCDRはwhiteではなくリスト(white)です。これは連想をドットペア表記で記述すると明確になります:

(lily white) ≡ (lily . (white))

Function: assoc-default key alist &optional test default

この関数は、keyにたいするマッチをalistから検索する。alistの各要素にたいして、この関数はkeyと要素(アトムの場合)、または要素のCAR(コンスの場合)を比較する。比較はtestに2つの引数 — 要素(か要素のCAR)とkey — を与えて呼び出すことにより行なわれる。引数はこの順番で渡されるので、正規表現(正規表現の検索を参照)を含むalistでは、string-matchを使用することにより有益な結果を得ることができる。testが省略またはnilなら比較にequalが使用される。

alistの要素がこの条件によりkeyとマッチすると、assoc-defaultはその要素の値をリターンする。要素がコンスなら値は要素のCDR、それ以外ならリターン値はdefaultとなる。

keyにマッチする要素がalistに存在しないければ、assoc-defaultはnilをリターンする。

Function: copy-alist alist

この関数は深さのレベルが2のalistのコピーをリターンする。この関数は各連想の新しいコピーを作成するので、元のalistを変更せずに新しいalistを変更できる。

(setq needles-per-cluster
      '((2 . ("Austrian Pine" "Red Pine"))
        (3 . ("Pitch Pine"))

        (5 . ("White Pine"))))
⇒
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(setq copy (copy-alist needles-per-cluster))
⇒
((2 "Austrian Pine" "Red Pine")
 (3 "Pitch Pine")
 (5 "White Pine"))

(eq needles-per-cluster copy)
     ⇒ nil
(equal needles-per-cluster copy)
     ⇒ t
(eq (car needles-per-cluster) (car copy))
     ⇒ nil
(cdr (car (cdr needles-per-cluster)))
     ⇒ ("Pitch Pine")

(eq (cdr (car (cdr needles-per-cluster)))
    (cdr (car (cdr copy))))
     ⇒ t

以下の例は、どのようにしてcopy-alistが他に影響を与えずにコピーの連想を変更可能なのかを示す:

(setcdr (assq 3 copy) '("Martian Vacuum Pine"))
(cdr (assq 3 needles-per-cluster))
     ⇒ ("Pitch Pine")

Function: assq-delete-all key alist

この関数は、delqを使用してマッチする要素を1つずつ削除するときのように、CARがkeyとeqであるようなすべての要素をalistから削除する。この関数は短くなったalistをリターンし、alistの元のリスト構造を変更することもよくある。正しい結果を得るために、alistに保存された値ではなくassq-delete-allのリターン値を使用すること。

(setq alist '((foo 1) (bar 2) (foo 3) (lose 4)))
     ⇒ ((foo 1) (bar 2) (foo 3) (lose 4))
(assq-delete-all 'foo alist)
     ⇒ ((bar 2) (lose 4))
alist
     ⇒ ((foo 1) (bar 2) (lose 4))

Function: rassq-delete-all value alist: この関数は、alistからCDRがvalueとeqであるようなすべての要素を削除する。この関数は短くなったリストをリターンし、alistの元のリスト構造を変更することもよくある。rassq-delete-allはassq-delete-allと似ているが、CARではなくalistの各連想のCDRを比較する。

5.9 プロパティリスト

プロパティーリスト(property list、短くはplist)は、ペアになった要素のリストです。各ペアはプロパティー名(通常はシンボル)とプロパティー値を対応づけます。以下はプロパティーリストの例です:

(pine cones numbers (1 2 3) color "blue")

このプロパティーリストはpineをcones、numbersを(1 2 3)、colorを"blue"に関連づけます。プロパティー名とプロパティー値には任意のLispオブジェクトを指定できますが、通常プロパティー名は(この例のように)シンボルです。

いくつかのコンテキストでプロパティーリストが使用されます。たとえば関数put-text-propertyはプロパティーリストを引数にとり、文字列やバッファー内のテキストにたいして、テキストプロパティーとテキストに適用するプロパティー値を指定します。テキストのプロパティを参照してください。

プロパティーリストが頻繁に使用される他の例は、シンボルプロパティーの保管です。すべてのシンボルはシンボルに関する様々な情報を記録するために、プロパティーのリストを処理します。これらのプロパティーはプロパティーリストの形式で保管されます。シンボルのプロパティを参照してください。

5.9.1 プロパティリストと連想リスト

連想リスト(連想リストを参照)は、プロパティーリストとよく似ています。連想リストとは対照的にプロパティー名は一意でなければならないので、プロパティーリスト内でペアの順序に意味はありません。

様々なLisp関数や変数に情報を付加するためには、連想リストよりプロパティーリストの方が適しています。プログラムでこのような情報すべてを1つの連想リストに保持する場合は、特定のLisp関数や変数にたいする連想をチェックする度にリスト全体を検索する必要が生じ、それにより遅くなる可能性があります。対照的に関数名や変数自体のプロパティーリストに同じ情報を保持すれば、検索ごとにそのプロパティーリストの長さだけを検索するようになり、通常はこちらの方が短時間で済みます。変数のドキュメントがvariable-documentationという名前のプロパティーに記録されているのはこれが理由です。同様にバイトコンパイラーも、特別に扱う必要がある関数を記録するためにプロパティーを使用します。

とはいえ連想リストにも独自の利点があります。アプリケーションに依存しますが、プロパティーを更新するより連想リストの先頭に連想を追加する方が高速でしょう。シンボルにたいするすべてのプロパティーは同じプロパティーリストに保管されるので、プロパティー名を異なる用途のために使用すると衝突の可能性があります(この理由により、そのプログラムで通常の変数や関数の名前につけるプレフィクスをプロパティー名の先頭につけて、一意と思われるプロパティー名を選ぶのはよいアイデアだと言える)。連想リストは、連想をリストの先頭にpushして、その後にある連想は無視されるので、スタックと同様に使用できます。これはプロパティーリストでは不可能です。

5.9.2 プロパティリストと外部シンボル

以下の関数はプロパティーリストを操作するために使用されます。これらの関数はすべて、プロパティー名の比較にeqを使用します。

Function: plist-get plist property

この関数はプロパティーリストplistに保管された、プロパティーpropertyの値をリターンする。この関数には不正な形式(malformed)のplist引数を指定できる。plistでpropertyが見つからないと、この関数はnilをリターンする。たとえば、

(plist-get '(foo 4) 'foo)
     ⇒ 4
(plist-get '(foo 4 bad) 'foo)
     ⇒ 4
(plist-get '(foo 4 bad) 'bad)
     ⇒ nil
(plist-get '(foo 4 bad) 'bar)
     ⇒ nil

Function: plist-put plist property value

この関数はプロパティーリストplistに、プロパティーpropertyの値としてvalueを保管する。この関数はplistを破壊的に変更するかもしれず、元のリスト構造を変更せずに新しいリストを構築することもある。この関数は変更されたプロパティーリストをリターンするので、plistを取得した場所に書き戻すことができる。たとえば、

(setq my-plist '(bar t foo 4))
     ⇒ (bar t foo 4)
(setq my-plist (plist-put my-plist 'foo 69))
     ⇒ (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
     ⇒ (bar t foo 69 quux (a))

Function: lax-plist-get plist property: plist-getと同様だがプロパティーの比較にeqではなくequalを使用する。

Function: lax-plist-put plist property value: plist-putと同様だがプロパティーの比較にeqではなくequalを使用する。

Function: plist-member plist property: この関数は与えられたpropertyがplistに含まれるなら非nilをリターンする。plist-getとは異なりこの関数は存在しないプロパティーと、値がnilのプロパティーを区別できる。実際にリターンされる値は、carがpropertyで始まるplistの末尾部分である。

6 シーケンス、配列、ベクター

シーケンス(sequence)型は2つの異なるLisp型 — リストと配列 — を結合した型です。言い換えると任意のリストはシーケンスであり任意の配列はシーケンスです。すべてのシーケンスがもつ共通な属性は、それぞれが順序づけされた要素のコレクションであることです。

配列(array)はスロットがその要素であるような、固定長のオブジェクトです。すべての要素に一定時間でアクセスできます。配列の4つの型として文字列、ベクター、文字テーブル、ブールベクターがあります。

リストは要素のシーケンスですが、要素は単一の基本オブジェクトではありません。リストはコンスセルにより作られ、要素ごとに1つのセルをもちます。n番目の要素を探すにはn個のコンスセルを走査する必要があるので、先頭から離れた要素ほどアクセスに時間を要します。しかしリストは要素の追加や削除が可能です。

以下の図はこれらの型の関連を表しています:

          _____________________________________________
         |                                             |
         |          Sequence                           |
         |  ______   ________________________________  |
         | |      | |                                | |
         | | List | |             Array              | |
         | |      | |    ________       ________     | |
         | |______| |   |        |     |        |    | |
         |          |   | Vector |     | String |    | |
         |          |   |________|     |________|    | |
         |          |  ____________   _____________  | |
         |          | |            | |             | | |
         |          | | Char-table | | Bool-vector | | |
         |          | |____________| |_____________| | |
         |          |________________________________| |
         |_____________________________________________|

6.1 シーケンス		任意の種類のシーケンスを許す関数。
6.2 配列		Emacs Lispの配列の特徴。
6.3 配列を操作する関数		配列に特化した関数。
6.4 ベクター		Emacs Lispベクターの特質。
6.5 ベクターのための関数		ベクターのための特別な関数。
6.6 文字テーブル		文字テーブルを扱う方法。
6.7 ブールベクター		ブールベクターを扱う方法。
6.8 オブジェクト用固定長リングの管理		オブジェクトの固定サイズのリングを管理する。

6.1 シーケンス

このセクションでは任意の種類のシーケンスを許す関数を説明します。

Function: sequencep object: この関数はobjectがリスト、ベクター、文字列、ブールベクター、文字テーブルならt、それ以外はnilをリターンする。

Function: length sequence

この関数はsequence内の要素の数をリターンする。sequenceがドットリストならwrong-type-argumentエラーがシグナルされる。循環リストは無限ループを引き起こす。文字テーブルではEmacsの最大文字コードより1大きい値が常にリターンされる。

関連する関数safe-lengthについてはDefinition of safe-lengthを参照のこと。

(length '(1 2 3))
    ⇒ 3

(length ())
    ⇒ 0

(length "foobar")
    ⇒ 6

(length [1 2 3])
    ⇒ 3

(length (make-bool-vector 5 nil))
    ⇒ 5

テキストの表現方法のstring-bytesも参照されたい。

ディスプレー上での文字列の幅を計算する必要があるなら、文字数だけを数えて各文字のディスプレー幅を計算しないlengthではなく、string-width (表示されるテキストのサイズを参照)を使用すること。

Function: elt sequence index

この関数はindexによりインデックスづけされた、sequenceの要素をリターンする。indexの値として妥当なのは、0からsequenceの長さより1小さい数までの範囲の整数。sequenceがリストなら範囲外の値はnthと同じように振る舞う。Definition of nthを参照のこと。それ以外なら範囲外の値はargs-out-of-rangeエラーを引き起こす。

(elt [1 2 3 4] 2)
     ⇒ 3

(elt '(1 2 3 4) 2)
     ⇒ 3

;; eltがどの文字をreturnするか明確にするためにstringを使用
(string (elt "1234" 2))
     ⇒ "3"

(elt [1 2 3 4] 4)
     error→ Args out of range: [1 2 3 4], 4

(elt [1 2 3 4] -1)
     error→ Args out of range: [1 2 3 4], -1

この関数はaref (配列を操作する関数を参照)とnth (Definition of nthを参照)を一般化したものである。

Function: copy-sequence seqr

This function returns a copy of seqr, which should be either a sequence or a record. The copy is the same type of object as the original, and it has the same elements in the same order. However, if seqr is empty, like a string or a vector of zero length, the value returned by this function might not be a copy, but an empty object of the same type and identical to seqr.

Storing a new element into the copy does not affect the original seqr, and vice versa. However, the elements of the copy are not copies; they are identical (eq) to the elements of the original. Therefore, changes made within these elements, as found via the copy, are also visible in the original.

If the argument is a string with text properties, the property list in the copy is itself a copy, not shared with the original’s property list. However, the actual values of the properties are shared. See section テキストのプロパティ.

この関数はドットリストでは機能しない。循環リストのコピーは無限ループを起こすだろう。

シーケンスをコピーする別の方法についてはコンスセルおよびリストの構築のappend、文字列の作成のconcat、ベクターのための関数のvconcatも参照されたい。

(setq bar '(1 2))
     ⇒ (1 2)

(setq x (vector 'foo bar))
     ⇒ [foo (1 2)]

(setq y (copy-sequence x))
     ⇒ [foo (1 2)]

(eq x y)
     ⇒ nil

(equal x y)
     ⇒ t

(eq (elt x 1) (elt y 1))
     ⇒ t

;; 一方のシーケンスの要素を置き換え
(aset x 0 'quux)
x ⇒ [quux (1 2)]
y ⇒ [foo (1 2)]

;; 共有された要素の内部を変更
(setcar (aref x 1) 69)
x ⇒ [quux (69 2)]
y ⇒ [foo (69 2)]

Function: reverse sequence

この関数はsequenceの要素を反転した要素をもつ新たなシーケンスを作成する。元となる引数sequenceは変更されない。文字テーブルは反転できないことに注意。

(setq x '(1 2 3 4))
     ⇒ (1 2 3 4)

(reverse x)
     ⇒ (4 3 2 1)
x
     ⇒ (1 2 3 4)

(setq x [1 2 3 4])
     ⇒ [1 2 3 4]

(reverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [1 2 3 4]

(setq x "xyzzy")
     ⇒ "xyzzy"

(reverse x)
     ⇒ "yzzyx"
x
     ⇒ "xyzzy"

Function: nreverse sequence

この関数はsequenceの要素を反転する。reverseとは異なり、元となるsequenceは変更されるかもしれない。

たとえば:

(setq x '(a b c))
     ⇒ (a b c)

x
     ⇒ (a b c)
(nreverse x)
     ⇒ (c b a)

;; 先頭にあったコンスセルが末尾となった
x
     ⇒ (a)

混乱しないように、通常は元となるリストを保持する同じ変数に、nreverseの結果を書き戻す:

(setq x (nreverse x))

お馴染の例(a b c)のnreverseを以下に図示する:

Original list head:                       Reversed list:
 -------------        -------------        ------------
| car  | cdr  |      | car  | cdr  |      | car | cdr  |
|   a  |  nil |<--   |   b  |   o  |<--   |   c |   o  |
|      |      |   |  |      |   |  |   |  |     |   |  |
 -------------    |   --------- | -    |   -------- | -
                  |             |      |            |
                   -------------        ------------

setqが不要なのでベクターはより単純になる:

(setq x [1 2 3 4])
     ⇒ [1 2 3 4]
(nreverse x)
     ⇒ [4 3 2 1]
x
     ⇒ [4 3 2 1]

reverseとは異なり、この関数は文字列では機能しない。asetを使用して文字列データを変更できても、文字列は不変として扱うことを強く推奨する。

Function: sort sequence predicate

この関数はsequenceを安定ソートする。この関数はすべてのシーケンスにたいしては機能せず、リストとベクターにたいしてのみ使用できることに注意されたい。sequenceがリストなら破壊的に変更される。この関数はソートされたsequenceをリターンして、要素の比較にはpredicateを使用する。安定ソートでは、ソートキーが等しい要素の相対順序がソートの前後で保たれる。この安定性は異なる条件により要素を並べ替えるために、連続してソートを行う場合に重要となる。

引数predicateは2つの引数を受け取る関数でなければならない。これはsequenceの2つの要素で呼び出される。昇順でソートするなら、1つ目の要素が2つ目の要素より“小”なら非nil、それ以外ならnilをリターンすること。

比較関数predicateは、少なくともsortの単一の呼び出しにおいて、与えられた任意の引数ペアにたいして信頼できる結果をリターンしなければならない。これは非対照的(antisymmetric)、すなわちaがbより小なら、bがaより小であってはならず、推移律(transitive)、すなわちaがbより小、かつbがcより小なら、aはcより小でなければならない。これらの要件に合致しない比較関数を使用すると、sortの結果は予想できない。

sortのリストにたいする破壊的側面は、CDRを変更することによりsequenceを形成するコンスセルを再配置することにある。非破壊ソート関数は、それらのソート順に要素を格納するために、新たなコンスセルを作成するだろう。オリジナルを破壊せずにソートしたコピーを望むなら、まずcopy-sequenceでコピーしてからソートすること。

ソートによりsequenceのコンスセルのCARは変化しない。元々sequence内で要素aを含むコンスセルは、ソート後もそのCARにaを保持する。しかしCDRの変更により、ソート後には異なる位置に出現する。たとえば:

(setq nums '(1 3 2 6 5 4 0))
     ⇒ (1 3 2 6 5 4 0)

(sort nums '<)
     ⇒ (0 1 2 3 4 5 6)

nums
     ⇒ (1 2 3 4 5 6)

警告 nums内のリストが0を含まないことに注意。これはソート前と同じコンスセルだがもはやリストの先頭ではない。ソート前に引数を保持していた変数がソート済みリスト全体を保持すると仮定してはならない! かわりにsortの結果を保存して、それを使うこと。ほとんどの場合、わたしたちは元のリストを保持していた変数に結果を書き戻すようにしている。

(setq nums (sort nums '<))

安定ソートの何たるかをより理解するには、以下のベクターのサンプルを考えてみよ。ソート後、carが8であるようなすべてのアイテムはvectorの先頭にグループ化されるが、それらの相対的な順序は保たれる。carが9であるようなすべてのアイテムはvectorの末尾にグループ化されるが、それらの相対的な順序も保たれる。

(setq
  vector
  (vector '(8 . "xxx") '(9 . "aaa") '(8 . "bbb") '(9 . "zzz")
          '(9 . "ppp") '(8 . "ttt") '(8 . "eee") '(9 . "fff")))
     ⇒ [(8 . "xxx") (9 . "aaa") (8 . "bbb") (9 . "zzz")
         (9 . "ppp") (8 . "ttt") (8 . "eee") (9 . "fff")]

(sort vector (lambda (x y) (< (car x) (car y))))
     ⇒ [(8 . "xxx") (8 . "bbb") (8 . "ttt") (8 . "eee")
         (9 . "aaa") (9 . "zzz") (9 . "ppp") (9 . "fff")]

ソートを行う他の関数についてはテキストのソートを参照のこと。sortの有用な例は、ドキュメント文字列へのアクセスのdocumentationを参照されたい。

seq.elライブラリーは、以下のようなプレフィクスseq-がついたシーケンス操作用の追加のマクロと関数を提供します。それらを使用するには、最初にseqライブラリーをロードしなければなりません。

このライブラリー内で定義されたすべての関数は、副作用をもちません。これらは引数として渡されたすべてのシーケンス(リスト、ベクター、文字列)を変更しません。特に明記しなければ、結果は入力と同じ型のシーケンスです。述語を受け取る関数では、それらは単一の関数である必要があります。

seq.elライブラリーは、シーケンシャルなデータ構造の追加型で機能するように拡張可能です。そのためにすべての関数はcl-defgenericを使用して定義されています。cl-defgenericを使用した拡張の追加に関する詳細は、Generic Functionsを参照してください。

Function: seq-elt sequence index

この関数はindex(有効な範囲は0からsequenceの長さより1少ない整数)で指定されたsequenceの要素をリターンする。ビルトインのシーケンス型にたいする範囲外(out-of-range)の値にたいして、seq-eltはeltと同様に振る舞う。詳細はDefinition of eltを参照のこと。

(seq-elt [1 2 3 4] 2)
⇒ 3

seq-eltはsetfを使用してセット可能なplaceをリターンする(setfマクロを参照)。

(setq vec [1 2 3 4])
(setf (seq-elt vec 2) 5)
vec
⇒ [1 2 5 4]

Function: seq-length sequence: この関数はsequence内の要素の個数をリターンする。ビルトインのシーケンス型にたいしてseq-lengthはlengthと同様に振る舞う。Definition of lengthを参照のこと。

Function: seqp sequence

この関数はsequenceがシーケンス(リストか配列)、またはseq.elのジェネリック関数を通じて定義されたすべての追加シーケンス型なら非nilをリターンする。

(seqp [1 2])
⇒ t

(seqp 2)
⇒ nil

Function: seq-drop sequence n

この関数はsequenceの最初のn個(整数)を除く、すべての要素をリターンする.nが0以下なら結果はsequence。

(seq-drop [1 2 3 4 5 6] 3)
⇒ [4 5 6]

(seq-drop "hello world" -4)
⇒ "hello world"

Function: seq-take sequence n

この関数はsequenceの最初のn個(整数)の要素をリターンする。nが0以下なら結果はnil。

(seq-take '(1 2 3 4) 3)
⇒ (1 2 3)

(seq-take [1 2 3 4] 0)
⇒ []

Function: seq-take-while predicate sequence

この関数はsequenceのメンバーを順にリターンし、predicateが最初にnilをリターンした要素の前で停止する。

(seq-take-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (1 2 3)

(seq-take-while (lambda (elt) (> elt 0)) [-1 4 6])
⇒ []

Function: seq-drop-while predicate sequence

この関数はpredicateが最初にnilをリターンした要素から、sequenceのメンバーを順にリターンする。

(seq-drop-while (lambda (elt) (> elt 0)) '(1 2 3 -1 -2))
⇒ (-1 -2)

(seq-drop-while (lambda (elt) (< elt 0)) [1 4 6])
⇒ [1 4 6]

Function: seq-do function sequence: この関数はsequenceの各要素にたいして、(恐らくは副作用を得るために)順番にfunctionを適用して、sequenceをリターンする。

Function: seq-map function sequence

この関数はsequenceの各要素にfunctionを適用した結果をリターンする。リターン値はリスト。

(seq-map #'1+ '(2 4 6))
⇒ (3 5 7)

(seq-map #'symbol-name [foo bar])
⇒ ("foo" "bar")

Function: seq-map-indexed function sequence

This function returns the result of applying function to each element of sequence and its index within seq. The returned value is a list.

(seq-map-indexed (lambda (elt idx)
                   (list idx elt))
                 '(a b c))
⇒ ((0 a) (b 1) (c 2))

Function: seq-mapn function &rest sequences

この関数はsequencesの各要素にfunctionを適用した結果をリターンする。 functionのarity (関数が受け取れる引数の個数。sub-arityを参照)はシーケンスの個数にマッチしなければならない。マッピングは最短のシーケンス終端で停止する。リターン値はリスト。

(seq-mapn #'+ '(2 4 6) '(20 40 60))
⇒ (22 44 66)

(seq-mapn #'concat '("moskito" "bite") ["bee" "sting"])
⇒ ("moskitobee" "bitesting")

Function: seq-filter predicate sequence

この関数はpredicateが非nilをリターンしたsequence内のすべての要素のリストをリターンする。

(seq-filter (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (1 3 5)

(seq-filter (lambda (elt) (> elt 0)) '(-1 -3 -5))
⇒ nil

Function: seq-remove predicate sequence

この関数はpredicateがnilをリターンしたsequence内のすべての要素のリストをリターンする。

(seq-remove (lambda (elt) (> elt 0)) [1 -1 3 -3 5])
⇒ (-1 -3)

(seq-remove (lambda (elt) (< elt 0)) '(-1 -3 -5))
⇒ nil

Function: seq-reduce function sequence initial-value

この関数はinitial-valueとsequenceの1つ目の要素でfunctionを呼び出し、次にその結果とsequenceの2つ目の要素でfunctionを呼び出し、その次にその結果とsequenceの3つ目の要素で、...と呼び出した結果をリターンする。functionは引数が2つの関数であること。sequenceが空なら、これはfunctionを呼び出さずにinitial-valueをリターンする。

(seq-reduce #'+ [1 2 3 4] 0)
⇒ 10

(seq-reduce #'+ '(1 2 3 4) 5)
⇒ 15

(seq-reduce #'+ '() 3)
⇒ 3

Function: seq-some predicate sequence

この関数はsequenceの各要素に順にpredicateを適用してリターンされた、最初の非nil値をリターンする。

(seq-some #'numberp ["abc" 1 nil])
⇒ t

(seq-some #'numberp ["abc" "def"])
⇒ nil

(seq-some #'null ["abc" 1 nil])
⇒ t

(seq-some #'1+ [2 4 6])
⇒ 3

Function: seq-find predicate sequence &optional default

この関数はpredicateが非nilをリターンした、sequence内の最初の要素をリターンする。predicateにマッチする要素がなければ、この関数はdefaultをリターンする。

この関数は見つかった要素がdefaultと等しい場合、要素が見つかったかどうかを知る術がないので曖昧さをもつことに注意。

(seq-find #'numberp ["abc" 1 nil])
⇒ 1

(seq-find #'numberp ["abc" "def"])
⇒ nil

Function: seq-every-p predicate sequence

この関数はsequenceの各要素にpredicateを適用して、すべてが非nilをリターンしたら非nilをリターンする。

(seq-every-p #'numberp [2 4 6])
⇒ t

(seq-every-p #'numberp [2 4 "6"])
⇒ nil

Function: seq-empty-p sequence

この関数はsequenceが空ならnilをリターンする。

(seq-empty-p "not empty")
⇒ nil

(seq-empty-p "")
⇒ t

Function: seq-count predicate sequence

この関数はsequence内でpredicateが非nilをリターンした要素の個数をリターンする。

(seq-count (lambda (elt) (> elt 0)) [-1 2 0 3 -2])
⇒ 2

Function: seq-sort function sequence: この関数はfunctionに応じてソートされたsequenceのコピーをリターンする。functionは2つの引数を受け取り、1つ目の引数が2つ目より前にソートされるべきなら非nilをリターンする。

Function: seq-sort-by function predicate sequence

This function is similar to seq-sort, but the elements of sequence are transformed by applying function on them before being sorted. function is a function of one argument.

(seq-sort-by #'seq-length #'> ["a" "ab" "abc"])
⇒ ["abc" "ab" "a"]

Function: seq-contains sequence elt &optional function

この関数はsequence内のeltとequalであるような最初の要素をリターンする。オプション引数functionが非nilなら、それはデフォルトのequalのかわりに使用する2つの引数を受け取る関数であること。

(seq-contains '(symbol1 symbol2) 'symbol1)
⇒ symbol1

(seq-contains '(symbol1 symbol2) 'symbol3)
⇒ nil

Function: seq-set-equal-p sequence1 sequence2 &optional testfn

This function checks whether sequence1 and sequence2 contain the same elements, regardless of the order. If the optional argument testfn is non-nil, it is a function of two arguments to use instead of the default equal.

(seq-set-equal-p '(a b c) '(c b a))
⇒ t

(seq-set-equal-p '(a b c) '(c b))
⇒ nil

(seq-set-equal-p '("a" "b" "c") '("c" "b" "a"))
⇒ t

(seq-set-equal-p '("a" "b" "c") '("c" "b" "a") #'eq)
⇒ nil

Function: seq-position sequence elt &optional function

この関数はeltとequalであるようなsequence内の最初の要素のインデックスをリターンする。オプション引数functionが非nilなら、それはデフォルトのequalのかわりに使用する2つの引数を受け取る関数であること。

(seq-position '(a b c) 'b)
⇒ 1

(seq-position '(a b c) 'd)
⇒ nil

Function: seq-uniq sequence &optional function

この関数は重複を削除したsequenceの要素のリストをリターンする。オプション引数functionが非nilなら、それはデフォルトのequalのかわりに使用する2つの引数を受け取る関数であること。

(seq-uniq '(1 2 2 1 3))
⇒ (1 2 3)

(seq-uniq '(1 2 2.0 1.0) #'=)
⇒ (1 2)

Function: seq-subseq sequence start &optional end

この関数はsequenceのstartからend(いずれも整数)までのサブセットをリターンする(endのデフォルトは最後の要素)。startかendが負ならsequenceの最後から数える。

(seq-subseq '(1 2 3 4 5) 1)
⇒ (2 3 4 5)

(seq-subseq '[1 2 3 4 5] 1 3)
⇒ [2 3]

(seq-subseq '[1 2 3 4 5] -3 -1)
⇒ [3 4]

Function: seq-concatenate type &rest sequences

この関数はsequencesを結合して作成されたtype型のシーケンスをリターンする。typeはvector、list、stringのいずれか。

(seq-concatenate 'list '(1 2) '(3 4) [5 6])
⇒ (1 2 3 4 5 6)

(seq-concatenate 'string "Hello " "world")
⇒ "Hello world"

Function: seq-mapcat function sequence &optional type

この関数はsequenceの各要素にfunctionを適用した結果に、seq-concatenateを適用した結果をリターンする。結果はtype型のシーケンス、またはtypeがnilならリストである。

(seq-mapcat #'seq-reverse '((3 2 1) (6 5 4)))
⇒ (1 2 3 4 5 6)

Function: seq-partition sequence n

この関数は長さnのサブシーケンスへグループ化したsequenceの要素のリストをリターンする。最後のシーケンスに含まれる要素はnより少ないかもしれない。nは整数であること。nが0以下の整数ならリターン値はnil。

(seq-partition '(0 1 2 3 4 5 6 7) 3)
⇒ ((0 1 2) (3 4 5) (6 7))

Function: seq-intersection sequence1 sequence2 &optional function

この関数はsequence1とsequence2の両方に出現する要素のリストをリターンする。オプション引数functionが非nilなら、それはデフォルトのequalのかわりに比較に使用する2つの引数を受け取る関数であること。

(seq-intersection [2 3 4 5] [1 3 5 6 7])
⇒ (3 5)

Function: seq-difference sequence1 sequence2 &optional function

この関数はsequence1に出現するがsequence2に出現しない要素のリストをリターンする。オプション引数functionが非nilなら、それはデフォルトのequalのかわりに比較に使用する2つの引数を受け取る関数であること。

(seq-difference '(2 3 4 5) [1 3 5 6 7])
⇒ (2 4)

Function: seq-group-by function sequence

この関数はsequenceの各要素にfunctionを適用して、その結果をキーとしてsequenceをalistに分割する。キーの比較にはequalを使用する。

(seq-group-by #'integerp '(1 2.1 3 2 3.2))
⇒ ((t 1 3 2) (nil 2.1 3.2))

(seq-group-by #'car '((a 1) (b 2) (a 3) (c 4)))
⇒ ((b (b 2)) (a (a 1) (a 3)) (c (c 4)))

Function: seq-into sequence type

この関数はシーケンスsequenceをtype型のシーケンスに変換する。typeはvector、string、listのいずれかであること。

(seq-into [1 2 3] 'list)
⇒ (1 2 3)

(seq-into nil 'vector)
⇒ []

(seq-into "hello" 'vector)
⇒ [104 101 108 108 111]

Function: seq-min sequence

この関数はsequenceの最小の要素をリターンする。sequenceの要素は数字かマーカー(マーカーを参照)でなければならない。

(seq-min [3 1 2])
⇒ 1

(seq-min "Hello")
⇒ 72

Function: seq-max sequence

この関数はsequenceの最大の要素をリターンする。sequenceの要素は数字かマーカーでなければならない。

(seq-max [1 3 2])
⇒ 3

(seq-max "Hello")
⇒ 111

Macro: seq-doseq (var sequence) body…: このマクロはdolist (dolistを参照)と同様だが、sequenceにリスト、ベクター、文字列のいずれかを指定できる点が異なる。これ主な利点は副作用である。

Macro: seq-let arguments sequence body…

このマクロはarguments内で定義される変数にsequenceの要素をバインドする。argumentsはネストされた非構造化を許容することにより、自身にシーケンスを含むことができる。

argumentsシーケンスには、sequenceの残りにバインドされる変数名が後続するような、&restマーカーを含めることもできる。

(seq-let [first second] [1 2 3 4]
  (list first second))
⇒ (1 2)

(seq-let (_ a _ b) '(1 2 3 4)
  (list a b))
⇒ (2 4)

(seq-let [a [b [c]]] [1 [2 [3]]]
  (list a b c))
⇒ (1 2 3)

(seq-let [a b &rest others] [1 2 3 4]
  others)

⇒ [3 4]

Function: seq-random-elt sequence

This function returns an element of sequence taken at random.

(seq-random-elt [1 2 3 4])
⇒ 3
(seq-random-elt [1 2 3 4])
⇒ 2
(seq-random-elt [1 2 3 4])
⇒ 4
(seq-random-elt [1 2 3 4])
⇒ 2
(seq-random-elt [1 2 3 4])
⇒ 1

If sequence is empty, this function signals an error.

6.2 配列

配列(array)オブジェクトは、いくつかのLispオブジェクトを保持するスロットをもち、これらのオブジェクトは配列の要素と呼ばれます。配列内の任意の要素は一定時間でアクセスされます。対照的にリスト内の要素のアクセスに要する時間は、その要素がリスト内のどの位置にあるかに比例します。

Emacsは4つの配列型 —文字列(strings、文字列型を参照)、ベクター(vectors、ベクター型を参照)、ブールベクター(bool-vectors、ブールベクター型を参照)、文字テーブル(char-tables、文字テーブル型を参照) — を定義しており、これらはすべて1次元です。ベクターと文字テーブルは任意の型の要素を保持できますが、文字列は文字だけ、ブールベクターはtかnilしか保持できません。

4種のすべての配列はこれらの特性を共有します:

配列の1番目の要素はインデックス0、2番目はインデックス1、...となる。これは0基準(zero-origin)のインデックスづけと呼ばれる。たとえば4要素の配列のインデックスは0、1、2、3。
配列の長さは一度配列が作成されたら固定されるので、既存の配列の長さは変更できない。
評価において配列は定数 — つまりそれ自身へと評価される。
配列の要素は関数arefで参照したり、関数asetで変更できる(配列を操作する関数を参照)。

配列を作成したとき、文字テーブル以外では長さを指定しなければなりません。文字テーブルの長さは文字コードの範囲により決定されるので長さを指定できません。

原則として、テキスト文字の配列が欲しい場合は、文字列とベクターのどちらかを使用できます。実際のところ4つの理由により,そのような用途にたいしては、わたしたちは常に文字列を選択します:

文字列は同じ要素をもつベクターと比較して占めるスペースが1/4である。
文字列の内容はテキストとして、より明解な方法によりプリントされる。
文字列はテキストプロパティーを保持できる。テキストのプロパティを参照のこと。
Emacsの特化した編集機能とI/O機能の多くが文字列だけに適用される。たとえば文字列をバッファーに挿入する方法では、文字のベクターをバッファーに挿入できない。文字列と文字を参照のこと

対照的に、(キーシーケンスのような)キーボード入力文字の配列では、多くのキーボード入力文字は文字列に収まる範囲の外にあるので、ベクターが必要になるでしょう。キーシーケンス入力を参照してください。

6.3 配列を操作する関数

このセクションではすべての型の配列に適用される関数を説明します。

Function: arrayp object

この関数はobjectが配列(ベクター、文字列、ブールベクター、文字テーブル)ならtをリターンする。

(arrayp [a])
     ⇒ t
(arrayp "asdf")
     ⇒ t
(arrayp (syntax-table))    ;; 文字テーブル
     ⇒ t

Function: aref arr index

This function returns the indexth element of the array or record arr. The first element is at index zero.

(setq primes [2 3 5 7 11 13])
     ⇒ [2 3 5 7 11 13]
(aref primes 4)
     ⇒ 11

(aref "abcdefg" 1)
     ⇒ 98           ; ‘b’のASCIIコードは98

シーケンスの関数eltも参照されたい。

Function: aset array index object

この関数はarrayのindex番目の要素をobjectにセットする。この関数はobjectをリターンする。

(setq w [foo bar baz])
     ⇒ [foo bar baz]
(aset w 0 'fu)
     ⇒ fu
w
     ⇒ [fu bar baz]

(setq x "asdfasfd")
     ⇒ "asdfasfd"
(aset x 3 ?Z)
     ⇒ 90
x
     ⇒ "asdZasfd"

arrayが文字列でobjectが文字でなければ、結果はwrong-type-argumentエラーとなる。この関数は文字列の挿入で必要なら、ユニバイト文字列をマルチバイト文字列に変換する。

Function: fillarray array object

この関数は配列arrayをobjectで充填するので、arrayのすべての要素はobjectになる。この関数はarrayをリターンする。

(setq a [a b c d e f g])
     ⇒ [a b c d e f g]
(fillarray a 0)
     ⇒ [0 0 0 0 0 0 0]
a
     ⇒ [0 0 0 0 0 0 0]

(setq s "When in the course")
     ⇒ "When in the course"
(fillarray s ?-)
     ⇒ "------------------"

arrayが文字列でobjectが文字でなければ、結果はwrong-type-argumentエラーとなる。

配列と判っているオブジェクトにたいしては、一般的なシーケンス関数copy-sequenceとlengthが有用なときがよくあります。シーケンスを参照してください。

6.4 ベクター

ベクター(vector)とは任意のLispオブジェクトを要素にもつことができる、一般用途のための配列です(対照的に文字列の要素は文字のみ。文字列と文字を参照)。Emacsではベクターはキーシーケンス(キーシーケンスを参照)、シンボル検索用のテーブル(シンボルの作成とinternを参照)、バイトコンパイルされた関数表現の一部(バイトコンパイルを参照)などの多くの目的で使用されます。

他の配列と同様、ベクターは0基準のインデックスづけを使用し、1番目の要素はインデックス0になります。

ベクターは角カッコ(square brackets)で囲まれた要素としてプリントされます。したがってシンボルa、b、aを要素にもつベクターは、[a b a]とプリントされます。Lisp入力として同じ方法でベクターを記述できます。

文字列や数値と同様にベクターは定数として評価され、評価された結果は同じベクターになります。ベクターの要素は評価も確認もされません。自己評価を行うフォームを参照してください。

以下はこれらの原理を表す例です:

(setq avector [1 two '(three) "four" [five]])
     ⇒ [1 two (quote (three)) "four" [five]]
(eval avector)
     ⇒ [1 two (quote (three)) "four" [five]]
(eq avector (eval avector))
     ⇒ t

6.5 ベクターのための関数

ベクターに関連した関数をいくつか示します:

Function: vectorp object

この関数はobjectがベクターならtをリターンする。

(vectorp [a])
     ⇒ t
(vectorp "asdf")
     ⇒ nil

Function: vector &rest objects

この関数は引数objectsを要素にもつベクターを作成してリターンする。

(vector 'foo 23 [bar baz] "rats")
     ⇒ [foo 23 [bar baz] "rats"]
(vector)
     ⇒ []

Function: make-vector length object

この関数は各要素がobjectに初期化された、length個の要素からなる新しいベクターをリターンする。

(setq sleepy (make-vector 9 'Z))
     ⇒ [Z Z Z Z Z Z Z Z Z]

Function: vconcat &rest sequences

この関数はsequencesのすべての要素を含む新しいベクターをリターンする。引数sequencesは真リスト、ベクター、文字列、ブールベクター。sequencesが与えられければ空のベクターがリターンされる。

値は空のベクター、またはすべての既存ベクターとeqではないような空ではない新しいベクターのいずれか。

(setq a (vconcat '(A B C) '(D E F)))
     ⇒ [A B C D E F]
(eq a (vconcat a))
     ⇒ nil

(vconcat)
     ⇒ []
(vconcat [A B C] "aa" '(foo (6 7)))
     ⇒ [A B C 97 97 foo (6 7)]

vconcat関数は、引数としてバイトコード関数オブジェクトも受け取ることができる。これはバイトコード関数オブジェクトの内容全体にアクセスするのを容易にするための特別な機能である。バイトコード関数オブジェクトを参照のこと。

結合を行なう他の関数については関数のマッピングのmapconcat、文字列の作成のconcat、コンスセルおよびリストの構築のappendを参照されたい。

append関数はベクターを同じ要素をもつリストに変換する方法も提供します:

(setq avector [1 two (quote (three)) "four" [five]])
     ⇒ [1 two (quote (three)) "four" [five]]
(append avector nil)
     ⇒ (1 two (quote (three)) "four" [five])

6.6 文字テーブル

文字テーブル(char-table)はベクターとよく似ていますが、文字テーブルは文字コードによりインデックスづけされます。文字テーブルのインデックスには、修飾キーをともなわない任意の有効な文字コードを使用できます。他の配列と同様に、arefとasetで文字テーブルの要素にアクセスできます。加えて、文字テーブルは追加のデータを保持するために、特定の文字コードに関連づけられていないエキストラスロット(extra slots)をもつことができます。ベクターと同様、文字テーブルは定数として評価され、任意の型の要素を保持できます。

文字テーブルはそれぞれサブタイプ(subtype)をもち、これは2つの目的をもつシンボルです:

サブタイプはそれがなんのための文字テーブルなのかを簡単に表す方法を提供する。たとえばディスプレーテーブル(display tables)はサブタイプがdisplay-tableの文字テーブルであり、構文テーブル(syntax tables)はサブタイプがsyntax-tableの文字テーブル。以下で説明するように関数char-table-subtypeを使用してサブタイプの問い合わせが可能。
サブタイプは文字テーブル内のいくつかのエキストラスロット(extra slots)を制御する。エキストラスロットの数は、そのサブタイプのchar-table-extra-slotsシンボルプロパティー(シンボルのプロパティを参照)により指定され、値は0から10の整数。サブタイプにそのようなシンボルプロパティーがなければ、その文字テーブルはエキストラスロットをもたない。

文字テーブルは親(parent)をもつことができ、これは他の文字テーブルです。文字テーブルが親をもつ場合、その文字テーブルで特定の文字cにたいしてnilが指定されていたら、親と指定された文字テーブルで指定された値を継承します。言い方を変えると、文字テーブルchar-tableでcにnilが指定されていたら、(aref char-table c)はchar-tableの親の値をリターンします。

文字テーブルはデフォルト値(default value)をもつこともできます。デフォルト値をもつとき、文字テーブルchar-tableがcにたいしてnil値を指定すると、(aref char-table c)はデフォルト値をリターンします。

Function: make-char-table subtype &optional init

サブタイプsubtype(シンボル)をもつ、新たに作成された文字テーブルをリターンする。各要素はinitに初期化され、デフォルトはnil。文字テーブルが作成された後で、文字テーブルのサブタイプを変更することはできない。

すべての文字テーブルは、インデックスとなる任意の有効な文字テーブルのための空間をもつので、文字テーブルの長さを指定する引数はない。

subtypeがシンボルプロパティーchar-table-extra-slotsをもつなら、それはその文字列テーブル内のエキストラスロットの数を指定する。値には0から10の整数を指定し、これ以外ならmake-char-tableはエラーとなる。subtypeがシンボルプロパティーchar-table-extra-slots(プロパティリストを参照)をもたなければ、その文字テーブルはエキストラスロットをもたない。

Function: char-table-p object: この関数はobjectが文字テーブルならt、それ以外はnilをリターンする。

Function: char-table-subtype char-table: この関数はchar-tableのサブタイプのシンボルをリターンする。

文字テーブルのデフォルト値にアクセスするための特別な関数は存在しません。これを行なうにはchar-table-rangeを使用します(以下参照)。

Function: char-table-parent char-table: この関数はchar-tableの親をリターンする。親は常にnilか他の文字テーブルである。

Function: set-char-table-parent char-table new-parent: この関数はchar-tableの親をnew-parentにセットする。

Function: char-table-extra-slot char-table n: この関数はchar-tableのエキストラスロットn (0基準)の内容をリターンする。文字テーブルのエキストラスロットの数は文字テーブルのサブタイプにより決定される。

Function: set-char-table-extra-slot char-table n value: この関数はchar-tableのエキストラスロットn (0基準)にvalueを格納する。

文字テーブルは1つの文字コードにたいして1つの要素値(element value)を指定できます。文字テーブルは文字セット全体にたいして値を指定することもできます。

Function: char-table-range char-table range

この関数は文字範囲rangeにたいしてchar-tableで指定された値をリターンする。可能なrangeは以下のとおり:

nil: デフォルト値への参照。
char: 文字charにたいする要素への参照(charは有効な文字コードであると仮定)。
(from . to): 包括的な範囲‘[from..to]’内のすべての文字を参照するコンスセル。

Function: set-char-table-range char-table range value

この関数はchar-table内の文字範囲rangeにたいして値をセットする。可能なrangeは以下のとおり:

nil: デフォルト値への参照。
t: 文字コード範囲の全体を参照。
char: 文字charにたいする要素への参照(charは有効な文字コードであると仮定)。
(from . to): 包括的な範囲‘[from..to]’内のすべての文字を参照するコンスセル。

Function: map-char-table function char-table

この関数はchar-tableの非nil値ではない各要素にたいして引数functionを呼び出す。functionの呼び出しでは2つの引数(keyとvalue)が指定される。keyはchar-table-rangeにたいする可能なrange (有効な文字か、同じ値を共有する文字範囲を指定するコンスセル(from . to))。valueは(char-table-range char-table key)がリターンする値。

全体として、functionに渡されるkey-valueのペアはchar-tableに格納されたすべての値を表す。

リターン値は常にnilである。map-char-table呼び出しを有用にするためにfunctionは副作用をもつこと。たとえば以下は構文テーブルを調べる方法:

(let (accumulator)
   (map-char-table
    #'(lambda (key value)
        (setq accumulator
              (cons (list
                     (if (consp key)
                         (list (car key) (cdr key))
                       key)
                     value)
                    accumulator)))
    (syntax-table))
   accumulator)
⇒
(((2597602 4194303) (2)) ((2597523 2597601) (3))
 ... (65379 (5 . 65378)) (65378 (4 . 65379)) (65377 (1))
 ... (12 (0)) (11 (3)) (10 (12)) (9 (0)) ((0 8) (3)))

6.7 ブールベクター

ブールベクター(bool-vector)はベクターとよく似ていますが、値にtとnilしか格納できません。ブールベクターの要素に非nil値の格納を試みたると、そこにはtが格納されます。すべての配列と同様、ブールベクターのインデックスは0から開始され、一度ブールベクターが作成されたら長さを変更することはできません。ブールベクターは定数として評価されます。

ブールベクターを処理する特別な関数がいくつかあります。その関数以外にも、他の種類の配列に使用されるのと同じ関数でブールベクターを操作できます。

Function: make-bool-vector length initial: initialに初期化されたlength要素の新しいブールベクターをリターンする。

Function: bool-vector &rest objects: この関数は引数objectsを要素にもつブールベクターを作成してリターンする。

Function: bool-vector-p object: この関数はobjectがブールベクターであればt、それ以外はnilをリターンする。

以下で説明するように、ブールベクターのセット処理を行なう関数がいくつかあります:

Function: bool-vector-exclusive-or a b &optional c: ブールベクターaとbのビットごとの排他的論理和(bitwise exclusive or)をリターンする。オプション引数cが与えられたら、この処理の結果はcに格納される。引数にはすべて同じ長さのブールベクターを指定すること。

Function: bool-vector-union a b &optional c: ブールベクターaとbのビットごとの論理和(bitwise or)をリターンする。オプション引数cが与えられたら、この処理の結果はcに格納される。引数にはすべて同じ長さのブールベクターを指定すること。

Function: bool-vector-intersection a b &optional c: ブールベクターaとbのビットごとの論理積(bitwise and)をリターンする。オプション引数cが与えられたら、この処理の結果はcに格納される。引数にはすべて同じ長さのブールベクターを指定すること。

Function: bool-vector-set-difference a b &optional c: ブールベクターaとbの差集合(set difference)をリターンする。オプション引数cが与えられたら、この処理の結果はcに格納される。引数にはすべて同じ長さのブールベクターを指定すること。

Function: bool-vector-not a &optional b: ブールベクターaの補集合(set complement)をリターンする。オプション引数bが与えられたら、この処理の結果はbに格納される。引数にはすべて同じ長さのブールベクターを指定すること。

Function: bool-vector-subsetp a b: Return t if every t value in a is also t in b, nil otherwise. All arguments should be bool vectors of the same length.

Function: bool-vector-count-consecutive a b i: iから始まるaの、bと等しい連続する要素の数をリターンする。aはブールベクターで、bはtかnil、iはaのインデックス。

Function: bool-vector-count-population a: ブールベクターaからtであるような要素の数をリターンする。

長さ8以下のブール値のプリント表記は1文字で表されます。

(bool-vector t nil t nil)
     ⇒ #&4"^E"
(bool-vector)
     ⇒ #&0""

他のベクター同様、vconcatを使用してブールベクターをプリントできます:

(vconcat (bool-vector nil t nil t))
     ⇒ [nil t nil t]

以下はブールベクターを作成、確認、更新する別の例です:

(setq bv (make-bool-vector 5 t))
     ⇒ #&5"^_"
(aref bv 1)
     ⇒ t
(aset bv 3 nil)
     ⇒ nil
bv
     ⇒ #&5"^W"

control-_の2進コードは11111、control-Wは10111なので、この結果は理にかなっています。

6.8 オブジェクト用固定長リングの管理

リング(ring)は挿入、削除、ローテーション、剰余(modulo)でインデックスづけされた、参照と走査(traversal)をサポートする固定長のデータ構造です。ringパッケージにより効率的なリングデータ構造が実装されています。このパッケージは、このセクションにリストした関数を提供します。

Emacsにあるkillリングやマークリングのようないくつかのリングは、実際には単なるリストとして実装されていることに注意してください。したがってこれらのリングにたいしては、以下の関数は機能しないでしょう。

Function: make-ring size: この関数はsizeオブジェクトを保持できる、新しいリングをリターンする。sizeは整数。

Function: ring-p object: この関数はobjectがリングならt、それ以外はnilをリターンする。

Function: ring-size ring: この関数はringの最大の要素数をリターンする。

Function: ring-length ring: この関数はringに現在含まれるオブジェクトの数をリターンする。値がring-sizeのリターンする値を超えることはない。

Function: ring-elements ring: この関数はring内のオブジェクトのリストをリターンする。リストの順序は新しいオブジェクトが先頭になる。

Function: ring-copy ring: この関数は新しいリングとしてringのコピーをリターンする。新しいリングはringと同じ(eqな)オブジェクトを含む。

Function: ring-empty-p ring: この関数はringが空ならt、それ以外はnilをリターンする。

リング内の1番新しい要素は常にインデックス0をもちます。より大きいインデックスは、より古い要素に対応します。インデックスはリング長のmoduloにより計算されます。インデックス-1は1番古い要素、-2は次に古い要素、...となります。

Function: ring-ref ring index: この関数はインデックスindexにあるring内のオブジェクトをリターンする。indexには負やリング長より大きい数を指定できる。ringが空ならring-refはエラーをシグナルする。

Function: ring-insert ring object

この関数は1番新しい要素としてobjectをringに挿入してobjectをリターンする。

リングが満杯なら新しい要素用の空きを作るために、挿入により1番古い要素が削除される。

Function: ring-remove ring &optional index: ringからオブジェクトを削除してそのオブジェクトをリターンする。引数indexはどのアイテムを削除するかを指定する。これがnilなら、それは1番古いアイテムを削除することを意味する。ringが空ならring-removeはエラーをシグナルする。

Function: ring-insert-at-beginning ring object

この関数は1番古い要素としてobjectをringに挿入する。リターン値に意味はない。

リングが満杯なら、この関数は挿入される要素のための空きを作るために1番新しい要素を削除する。

リングサイズを超過しないよう注意すれば、そのリングをFIFO(first-in-first-out: 先入れ先出し)のキューとして使用することができます。たとえば:

(let ((fifo (make-ring 5)))
  (mapc (lambda (obj) (ring-insert fifo obj))
        '(0 one "two"))
  (list (ring-remove fifo) t
        (ring-remove fifo) t
        (ring-remove fifo)))
     ⇒ (0 t one t "two")

7 Records

The purpose of records is to allow programmers to create objects with new types that are not built into Emacs. They are used as the underlying representation of cl-defstruct and defclass instances.

Internally, a record object is much like a vector; its slots can be accessed using aref and it can be copied using copy-sequence. However, the first slot is used to hold its type as returned by type-of. Also, in the current implementation records can have at most 4096 slots, whereas vectors can be much larger. Like arrays, records use zero-origin indexing: the first slot has index 0.

The type slot should be a symbol or a type descriptor. If it’s a type descriptor, the symbol naming its type will be returned; Type Descriptors. Any other kind of object is returned as-is.

The printed representation of records is ‘#s’ followed by a list specifying the contents. The first list element must be the record type. The following elements are the record slots.

To avoid conflicts with other type names, Lisp programs that define new types of records should normally use the naming conventions of the package where these record types are introduced for the names of the types. Note that the names of the types which could possibly conflict might not be known at the time the package defining a record type is loaded; they could be loaded at some future point in time.

A record is considered a constant for evaluation: the result of evaluating it is the same record. This does not evaluate or even examine the slots. See section 自己評価を行うフォーム.

7.1 Record Functions

Function: recordp object

This function returns t if object is a record.

(recordp #s(a))
     ⇒ t

Function: record type &rest objects

This function creates and returns a record whose type is type and remaining slots are the rest of the arguments, objects.

(record 'foo 23 [bar baz] "rats")
     ⇒ #s(foo 23 [bar baz] "rats")

Function: make-record type length object

This function returns a new record with type type and length more slots, each initialized to object.

(setq sleepy (make-record 'foo 9 'Z))
     ⇒ #s(foo Z Z Z Z Z Z Z Z Z)

7.2 Backward Compatibility

Code compiled with older versions of cl-defstruct that doesn’t use records may run into problems when used in a new Emacs. To alleviate this, Emacs detects when an old cl-defstruct is used, and enables a mode in which type-of handles old struct objects as if they were records.

Function: cl-old-struct-compat-mode arg: If arg is positive, enable backward compatibility with old-style structs.

8 ハッシュテーブル

ハッシュテーブル(hash table)は非常に高速なルックアップテーブルの一種で、キーに対応する値をマップするという点ではalist(連想リストを参照)に似ています。ハッシュテーブルは以下の点でalistと異なります:

ハッシュテーブルでのルックアップ(lookup: 照合)は、巨大なテーブルにたいして非常に高速である — 実際のところルックアップに必要な時間は、そのテーブルに格納されている要素数とは基本的に無関係である。ハッシュテーブルには一定のオーバーヘッドが多少あるので、小さいテーブル(数十の要素)ではalistのほうが高速だろう。
ハッシュテーブル内の対応関係に特定の順序はない。
2つのalistで共通の末尾(tail)を共有させるような、2つのハッシュテーブル間で構造を共有する方法はない。

Emacs Lispは一般的な用途のハッシュテーブルデータ型とともに、それらを処理する一連の関数を提供します。ハッシュテーブルは‘#s’、その後にハッシュテーブルのプロパティーと内容を指定するリストが続く、特別なプリント表現をもちます。ハッシュテーブルの作成を参照してください(ハッシュ表記の最初に使用される‘#’文字は、読み取り表現をもたないオブジェクトのプリント表現であり、これはハッシュテーブルに何も行わない。プリント表現と読み取り構文を参照のこと)。

obarray(オブジェクト配列)もハッシュテーブルの一種ですが、これらは異なる型のオブジェクトであり、intern(インターン)されたシンボルを記録するためだけに使用されます(シンボルの作成とinternを参照)。

8.1 ハッシュテーブルの作成

ハッシュテーブルを作成する基本的な関数はmake-hash-tableです。

Function: make-hash-table &rest keyword-args

この関数は指定された引数に対応する新しいハッシュテーブルを作成する。引数はキーワード(特別に認識される独自のシンボル)と、それに対応する値を交互に指定することで構成される。

make-hash-tableではいくつかのキーワードが意味をもつが、実際に知る必要があるのは:testと:weaknessの2つだけである。

:test test

これはそのハッシュテーブルにたいしてキーを照合する方法を指定する。デフォルトはeqlであり他の代替としてはeqやequalがある:

eql: キーが数字ならそれらがequal、つまりそれらの値が等しくどちらも整数か浮動少数点数なら同一。それ以外なら別の2つのオブジェクトは決して同一とならない。
eq: 別の2つのLispオブジェクトはすべて別のキーになる。
equal: 別の2つのLispオブジェクトで、それらがequalなら同一のキーである。

testにたいして追加の選択肢を定義するために、define-hash-table-test (ハッシュの比較の定義を参照)を使用することができる。

:weakness weak

ハッシュテーブルのweakness(強度)は、ハッシュテーブル内に存在するキーと値をガーベージコレクションから保護するかどうかを指定する。

値weakにはnil、key、value、key-or-value、key-and-value、またはt(key-and-valueのエイリアス)のいずれかを指定しなければならない。weakがkeyならそのハッシュテーブルは、(キーが他の場所で参照されていなければ)ハッシュテーブルのキーがガーベージコレクトされるのを妨げられない。ある特定のキーがガーベージコレクトされると、それに対応する連想はハッシュテーブルから削除される。

weakがvalueならそのハッシュテーブルは、(値が他の場所で参照されていなければ)ハッシュテーブルの値がガベージコレクトされるのを妨げませんられない。ある特定の値がガーベージコレクトされると、それに対応する連想はハッシュテーブルから削除される。

weakがkey-and-value(かt)なら、その連想を保護するためにはキーと値の両方が生きていなければならない。したがってそのハッシュテーブルは、キーと値の一方だけをガーベージコレクトから守ることはしない。キーか値のどちらか一方がガーベージコレクトされたら、その連想は削除される。

weakがkey-or-valuenara、キーか値のどちらか一方で、その連想を保護することができる。したがってキーと値の両方がガベージコレクトされたときだけ(それがハッシュテーブル自体にたいする参照でなければ)、ハッシュテーブルからその連想が削除される。

weakのデフォルトはnilなので、ハッシュテーブルから参照されているキーと値はすべてガーベージコレクションから保護される。

:size size

これはそのハッシュテーブルに保管しようとしている、連想の数にたいするヒントを指定する。数が概算で判っていれば、この方法でそれを指定して処理を若干効率的にすることができる。小さすぎるサイズを指定すると、そのハッシュテーブルは必要に応じて自動的に拡張されるが、これを行なうために時間が余計にかかる。

デフォルトのサイズは65。

:rehash-size rehash-size

ハッシュテーブルに連想を追加するとき、そのテーブルが満杯ならテーブルを自動的に拡張する。この値はその際にどれだけハッシュテーブルを拡張するかを指定する。

If rehash-size is an integer, it should be positive, and the hash table grows by adding approximately that much to the nominal size. If rehash-size is floating point, it had better be greater than 1, and the hash table grows by multiplying the old size by approximately that number.

デフォルト値は1.5。

:rehash-threshold threshold

This specifies the criterion for when the hash table is full (so it should be made larger). The value, threshold, should be a positive floating-point number, no greater than 1. The hash table is full whenever the actual number of entries exceeds the nominal size multiplied by an approximation to this value. The default for threshold is 0.8125.

ハッシュテーブルのプリント表現を使用して、新しいハッシュテーブルを作成することもできます。指定されたハッシュテーブル内の各要素が、有効な入力構文(プリント表現と読み取り構文を参照)をもっていれば、Lispリーダーはこのプリント表現を読み取ることができます。たとえば以下は値val1(シンボル)と300(数字)に関連づけられた、キーkey1とkey2(両方ともシンボル)を、新しいハッシュテーブルに指定します。

#s(hash-table size 30 data (key1 val1 key2 300))

ハッシュテーブルのプリント表現は‘#s’と、その後の‘hash-table’で始まるリストにより構成されます。このリストの残りの部分はそのハッシュテーブルのプロパティーと初期内容を指定する、0個以上のプロパティーと値からなるペアで構成されるべきです。プロパティーと値はそのまま読み取られます。有効なプロパティー名はsize、test、weakness、rehash-size、rehash-threshold、dataです。dataプロパティーは、初期内容にたいするキーと値のペアのリストであるべきです。他のプロパティーは、上記で説明したmake-hash-tableのキーワード(:size、:testなど)と同じ意味をもちます。

バッファーやフレームのような、入力構文をもたないオブジェクトを含んだ初期内容をもつハッシュテーブルを指定できないことに注意してください。そのようなオブジェクトは、ハッシュテーブルを作成した後に追加します。

8.2 ハッシュテーブルへのアクセス

このセクションではハッシュテーブルにアクセスしたり、連想を保管する関数を説明します。比較方法による制限がない限り、一般的には任意のLispオブジェクトをハッシュキーとして使用できます。

Function: gethash key table &optional default: この関数はtableのkeyを照合してそれに関連づけられたvalue、table内にkeyをもつ連想が存在しなければdefaultをリターンする。

Function: puthash key value table: この関数はtable内に値valueをもつkeyの連想を挿入します。tableがすでにkeyの連想をもつなら、valueで古い連想値を置き換える。

Function: remhash key table

この関数はtableにkeyの連想があればそれを削除する。keyが連想をもたなければremhashは何も行なわない。

Common Lispに関する注意: Common Lispではremhashが実際に連想を削除したときは非nil、それ以外はnilをリターンする。Emacs Lispではremhashは常にnilをリターンする。

Function: clrhash table

この関数はハッシュテーブルtableからすべての連想を削除するので、そのハッシュテーブルは空になる。これはハッシュテーブルのクリーニング(clearing)とも呼ばれる。

Common Lispに関する注意: Common Lispではclrhashは空のtableをリターンする。Emacs Lispではnilをリターンする。

Function: maphash function table: この関数はtable内の各連想にたいして一度ずつfunctionを呼び出す。関数functionは2つの引数 — tableにリストされたkeyと、それに関連づけられたvalue — を受け取ること。maphashはnilをリターンする。

8.3 ハッシュの比較の定義

define-hash-table-testでキーを照合する新しい方法を定義できます。この機能を使用するにはハッシュテーブルの動作方法と、ハッシュコード(hash code)の意味を理解する必要があります。

概念的にはハッシュテーブルを1つの連想を保持できるスロットがたくさんある巨大な配列として考えることができます。キーを照合するにはまず、gethashがキーから整数のハッシュコードを計算します。配列内のインデックスを生成するために、gethashは配列の長さからこの整数のmoduloを得ます。それからキーが見つかったかどうか確認するためにそのスロット、もし必要なら近くのスロットを探します。

したがってキー照合の新しい方法を定義するためには、キーからハッシュコードを計算する関数と、2つのキーを直接比較する関数の両方が必要です。

Function: define-hash-table-test name test-fn hash-fn

この関数はnameという名前の新たなハッシュテーブルテストを定義します。

この方法でnameを定義した後は、make-hash-tableの引数testにこれを使用することができる。これを行なう際は、そのハッシュテーブルのキー値の比較にtest-fn、キー値からハッシュコードを計算するためにhash-fnを使用することになる。

関数test-fnは2つの引数(2つのキー)をとり、それらが同一と判断されたときは非nilをリターンする。

関数hash-fnは1つの引数(キー)を受け取り、そのキーのハッシュコード(整数)をリターンすること。よい結果を得るために、その関数は負の整数を含む整数の全範囲をハッシュコードに使用するべきある。

指定された関数は、プロパティーhash-table-testの配下の、nameというプロパティーリストに格納される。そのプロパティーの値形式は(test-fn hash-fn)。

Function: sxhash-equal obj

この関数はLispオブジェクトobjのハッシュコードをリターンする。リターン値はobjと、それが指す別のLispオブジェクトの内容を表す整数。

If two objects obj1 and obj2 are equal, then (sxhash-equal obj1) and (sxhash-equal obj2) are the same integer.

If the two objects are not equal, the values returned by sxhash-equal are usually different, but not always; once in a rare while, by luck, you will encounter two distinct-looking objects that give the same result from sxhash-equal.

Common Lisp note: In Common Lisp a similar function is called sxhash. Emacs provides this name as a compatibility alias for sxhash-equal.

Function: sxhash-eq obj

This function returns a hash code for Lisp object obj. Its result reflects identity of obj, but not its contents.

If two objects obj1 and obj2 are eq, then (sxhash-eq obj1) and (sxhash-eq obj2) are the same integer.

Function: sxhash-eql obj

This function returns a hash code for Lisp object obj suitable for eql comparison. I.e. it reflects identity of obj except for the case where the object is a float number, in which case hash code is generated for the value.

If two objects obj1 and obj2 are eql, then (sxhash-eql obj1) and (sxhash-eql obj2) are the same integer.

以下はlcaseを区別しない文字列のキーをもつハッシュテーブルを作成する例です。

(defun case-fold-string= (a b)
  (eq t (compare-strings a nil nil b nil nil t)))
(defun case-fold-string-hash (a)
  (sxhash-equal (upcase a)))

(define-hash-table-test 'case-fold
  'case-fold-string= 'case-fold-string-hash)

(make-hash-table :test 'case-fold)

以下は事前に定義されたテスト値equalと等価なテストを行なうハッシュテーブルを定義できるという例です。キーは任意のLispオブジェクトで、equalに見えるオブジェクトは同じキーと判断されます。

(define-hash-table-test 'contents-hash 'equal 'sxhash-equal)

(make-hash-table :test 'contents-hash)

8.4 ハッシュテーブルのためのその他関数

以下はハッシュテーブルに作用する他の関数です。

Function: hash-table-p table: この関数はtableがハッシュテーブルオブジェクトなら非nilをリターンする。

Function: copy-hash-table table: この関数はtableのコピーを作成してリターンする。そのテーブル自体がコピーされたものである場合のみ、キーと値が共有される。

Function: hash-table-count table: この関数はtable内の実際のエントリー数をリターンする。

Function: hash-table-test table: この関数はハッシュを行なう方法と、キーを比較する方法を指定するために、table作成時に与えられたtestの値をリターンする。ハッシュテーブルの作成のmake-hash-tableを参照されたい。

Function: hash-table-weakness table: この関数はハッシュテーブルtableに指定されたweakの値をリターンする。

Function: hash-table-rehash-size table: この関数はtableのrehash-sizeをリターンする。

Function: hash-table-rehash-threshold table: この関数はtableのrehash-thresholdをリターンする。

Function: hash-table-size table: この関数はtableの現在の定義されたサイズをリターンする。

9 シンボル

シンボル(symbol)は一意な名前をもつオブジェクトです。このチャプターではシンボル、シンボルの構成要素とプロパティーリスト、およびシンボルの作成とインターンする方法を説明します。別のチャプターではシンボルを変数として使用したり、関数名として使用する方法が説明されています。変数と関数を参照してください。シンボルの正確な入力構文については、シンボル型を参照してください。

symbolpを使用して、任意のLispオブジェクトがシンボルかどうかをテストできます:

Function: symbolp object: この関数はobjectがシンボルならt、それ以外はnilをリターンする。

9.1 シンボルの構成要素

各シンボルは4つの構成要素(もしくは“セル”)をもち、構成要素はそれぞれ別のオブジェクトを参照します:

プリント名(print name): そのシンボルの名前。
値(value): 変数としてのそのシンボルの現在値。
関数(function): そのシンボルの関数定義。シンボル、キーマップ、キーボードマクロも保持できる。
プロパティーリスト(property list): そのシンボルのプロパティーリスト。

プリント名のセルは常に文字列を保持し、それを変更することはできません。他の3つのセルには、任意のLispオブジェクトをセットすることができます。

プリント名のセルはシンボルの名前となる文字列を保持します。シンボルはシンボル名によりテキストとして表されるので、2つのシンボルが同じ名前をもたないことが重要です。Lispリーダーはシンボルを読み取るごとに、それを新規作成する前に、指定されたシンボルがすでに存在するかを調べます。シンボルの名前を得るには関数symbol-name(シンボルの作成とinternを参照)を使用します。

値セルは変数としてのシンボルの値(そのシンボル自身がLisp式として評価されたときに得る値)を保持します。ローカルバインディング(local binding)やスコーピングルール(scoping rules)等のような複雑なものを含めて、変数のセットや取得方法については変数を参照してください。ほとんどのシンボルは値として任意のLispオブジェクトをもつことができますが、一部の特別なシンボルは変更できない値をもちます。これらにはnil、t、および名前が‘:’で始まるすべてのシンボル(キーワード(keyword)と呼ばれる)が含まれます。変更不可な変数を参照してください。

関数セルはシンボルの関数定義を保持します。実際はにはfooの関数セルの中に保管されている関数を意味するときに、“関数foo”といってそれを参照することがよくあります。わたしたちは必要なときだけ、これを明確に区別することにします。関数セルは通常は関数(関数を参照)か、マクロ(マクロを参照)を保持するために使用されます。しかし関数セルはシンボル(シンボル関数インダイレクションを参照)、キーボードマクロ(キーボードマクロを参照)、キーマップ(キーマップを参照)、またはオートロードオブジェクト(自動ロードを参照)を保持するためにも使用できます。シンボルの関数セルの内容を得るには、関数symbol-function (関数セルの内容へのアクセスを参照)を使用します。

プロパティーリストのセルは、通常は正しくフォーマットされたプロパティーリストを保持するべきです。シンボルのプロパティーリストを得るには関数symbol-plistを使用します。シンボルのプロパティを参照してください。

マクロセルと値セルがvoid(空)のときもあります。voidとはそのセルがどのオブジェクトも参照していないことを意味します(これはシンボルvoidを保持するのともシンボルnilを保持するのとも異なる)。voidの関数セルまたは値セルを調べようとすると結果は‘Symbol's value as variable is void’のようなエラーとなります。

各シンボルは値セルと関数セルを別個にもつので、変数名と関数名が衝突することはありません。たとえばシンボルbuffer-file-nameが値(カレントバッファーでvisitされているファイルの名前)をもつと同様に、関数定義(ファイルの名前をリターンするプリミティブ関数)をもつことができます:

buffer-file-name
     ⇒ "/gnu/elisp/symbols.texi"
(symbol-function 'buffer-file-name)
     ⇒ #<subr buffer-file-name>

9.2 シンボルの定義

定義(definition)とは、特別な方法での使用の意図を宣言する特別な種類のLisp式です。定義とは通常はシンボルにたいする値を指定するか、シンボルにたいする1つの種類の使用についての意味とその方法で使用する際のシンボルの意味のドキュメントを指定します。したがってシンボルを変数として定義すると、その変数の初期値に加えてその変数のドキュメントを提供できます。

defvarとdefconstはグローバル変数(global variable) — Lispプログラムの任意の箇所からアクセスできる変数 — として定義するためのスペシャルフォームです。変数についての詳細は変数を参照してください。カスタマイズ可能な変数を定義するにはdefcustom (サブルーチンとしてdefvarも呼び出す)を使用します(カスタマイズ設定を参照)。

最初にシンボルが変数として定義されていなくても、原則としてsetqで任意のシンボルに値を割り当てることができます。しかし使用したいグローバル変数それぞれにたいして変数定義を記述するべきです。さもないとレキシカルスコープ(変数のバインディングのスコーピングルールを参照)が有効なときに変数が評価されたると、あなたのLispプログラムが正しく動作しないかもしれません。

defunはラムダ式(lambda expression)を生成して、そのシンボルの関数セルに格納することにより、そのシンボルを関数として定義します。したがってこのシンボルの関数定義は、そのラムダ式になります(関数セルの内容を意味する用語“関数定義(function definition)”は、defunがシンボルに関数としての定義を与えるというアイデアに由来する)。関数を参照してください。

defmacroはシンボルをマクロとして定義します。これはマクロオブジェクトを作成してシンボルの関数セルにそれを格納します。シンボルにはマクロと関数を与えることができますが、マクロと関数定義はどちらも関数セルに保持されるのにたいし、関数セルに保持できるのは常にただ1つのLispオブジェクトなので、一度に両方を行なうことはできないことに注意してください。マクロを参照してください。

前に注記したようにEmacs Lispではシンボルを(たとえばdefvarで)変数として定義して、同じシンボルを(たとえばdefunで)関数やマクロとして両方定義することができます。このような定義は衝突しません。

These definitions also act as guides for programming tools. For example, the C-h f and C-h v commands create help buffers containing links to the relevant variable, function, or macro definitions. See Name Help in The GNU Emacs Manual.

9.3 シンボルの作成とintern

GNU Emacs Lispでシンボルが作成される方法を理解するには、Lispがシンボルを読み取る方法を理解しなければなりません。Lispは、同じ文字綴りを読み取ったら、毎回同じシンボルを見つけることを保証しなければなりません。これに失敗すると、完全な混乱を招くでしょう。

Lispリーダーがシンボルに出会うと、Lispリーダーは名前のすべての文字を読み取ります。その後Lispリーダーはobarray(オブジェクト配列)と呼ばれるテーブル内のインデックスを決めるために、これらの文字をハッシュ(hash)します。ハッシュ化(hashing)は何かを照合するのに効果的な方法です。たとえばJan Jonesを見つけるときは、電話帳を表紙から1頁ずつ探すのではなくJの頁から探し始めます。これはハッシュ化の簡単なバージョンです。obarrayの各要素は与えられたハッシュコードとともに、すべてのシンボルを保持するバケット(bucket)です。与えられた名前を探すためには、バケットの中からハッシュコードがその名前であるような、すべてのシンボルを探すのが効果的です(同じアイデアは一般的なEmacsのハッシュテーブルでも使用されていがこれらはデータ型が異なる。ハッシュテーブルを参照されたい)。

探している名前のシンボルが見つかったら、リーダーはそのシンボルを使用します。obarrayにその名前のシンボルが含まれなければ、リーダーは新しいシンボルを作成してそれをobarrayに追加します。特定の名前のシンボルを探して追加することをインターン(intern)と言い、これが行なわれた後はそのシンボルはインターンされたシンボル(interned symbol)と呼ばれます。

インターンすることによりある特定の名前のシンボルは、各obarrayに1つだけであることが保証されます。同じ名前のシンボルが他に存在するかもしれませんが、同じobarrayには存在しません。したがってリーダーは、(同じobarrayを読みつづける限り)同じ名前にたいして同じシンボルを取得します。

インターンは通常はリーダー内で自動的に発生しますが、他のプログラムがこれを行なう必要がある場合もあります。たとえばM-xコマンドはその後にミニバッファーを使用してコマンド名を文字列として取得して、その文字列をインターンしてからインターンされたその名前のシンボルを得ます。

すべてのシンボルを含むobarrayはありません。実際にどのobarrayにも含まれないシンボルがいくつかあります。これらはインターンされていないシンボル(uninterned symbols)と呼ばれます。インターンされていないシンボルも、他のシンボルと同じく4つのセルをもちます。しかしインターンされていないシンボルへのアクセスを得る唯一の方法は、他の何らかのオブジェクトとして探すか、変数の値として探す方法だけです。

インターンされていないシンボルの作成は、Lispコードを生成するとき有用です。なぜなら作成されたコード内で変数として使用されているインターンされていないシンボルは、他のLispプログラムで使用されている任意の変数と競合することはありえないからです。

Emacs Lispではobarrayはベクターです。ベクター内の各要素がバケットになります。要素の値は、名前がそのバケットにハッシュされるようなインターンされたシンボル、またはバケットが空のときは0です。インターンされたシンボルは、そのバケット内の次のシンボルへの内部リンク(ユーザーからは見えない)をもちます。これらのリンクは不可視なので、mapatoms (以下参照)を使用する方法をのぞき、obarray内のすべてのシンボルを探す方法はありません。バケット内のシンボルの順番に意味はありません。

空のobarrayではすべての要素が0なので、(make-vector length 0)でobarrayを作成することができます。obarrayを作成する有効な方法はこれだけです。長さに素数を指定するとよいハッシュ化がされる傾向があります。2の累乗から1減じた長さもよい結果を生む傾向があります。

自分でobarrayにシンボルを置かないでください。これはうまくいきません — obarrayに正しくシンボルを入力できるのはinternだけです。

Common Lispに関する注意: Common Lispとは異なりEmacs Lispは1つのシンボルを複数のobarrayにインターンする方法を提供しない。

以下の関数のほとんどは、引数に名前とobarrayをとります。名前が文字列以外、またはobarrayがベクター以外ならwrong-type-argumentエラーがシグナルされます。

Function: symbol-name symbol

この関数はsymbolの名前を文字列としてリターンする。たとえば:

(symbol-name 'foo)
     ⇒ "foo"

警告: 文字の置き換えにより文字列を変更すると、それはシンボルの名前を変更しますが、obarrayの更新には失敗するので行なわないこと!

Function: make-symbol name

この関数は新たに割り当てられた、名前がname(文字列でなかればならない)であるような、インターンされていないシンボルをリターンする。このシンボルの値と関数はvoidで、プロパティーリストはnil。以下の例ではsymの値はfooとeqではない。なぜならこれは名前が‘foo’という、インターンされていないシンボルだからである。

(setq sym (make-symbol "foo"))
     ⇒ foo
(eq sym 'foo)
     ⇒ nil

Function: gensym &optional prefix: This function returns a symbol using make-symbol, whose name is made by appending gensym-counter to prefix. The prefix defaults to "g".

Function: intern name &optional obarray

この関数は名前がnameであるような、インターンされたシンボルをリターンする。オブジェクト配列obarrayの中にそのようなシンボルが存在しなければ、internは新たにシンボルを作成してobarrayに追加してそれをリターンする。obarrayが省略されると、グローバル変数obarrayの値が使用される。

(setq sym (intern "foo"))
     ⇒ foo
(eq sym 'foo)
     ⇒ t

(setq sym1 (intern "foo" other-obarray))
     ⇒ foo
(eq sym1 'foo)
     ⇒ nil

Common Lispに関する注意: Common Lispでは既存のシンボルをobarrayにインターンできる。Emacs Lispではinternの引数はシンボルではなく文字列なのでこれを行なうことはできない。

Function: intern-soft name &optional obarray

この関数はobarray内の名前がnameのシンボル、obarrayにその名前のシンボルが存在しなければnilをリターンする。したがって与えられた名前のシンボルがすでにインターンされているかテストするために、intern-softを使用することができる。obarrayが省略されるとグローバル変数obarrayの値が使用される。

引数nameにはシンボルも使用できる。この場合、指定されたobarrayにnameがインターンされていればname、それ以外ならnilをリターンする。

(intern-soft "frazzle")        ; そのようなシンボルは存在しない
     ⇒ nil
(make-symbol "frazzle")        ; インターンされていないシンボルを作成する
     ⇒ frazzle

(intern-soft "frazzle")        ; そのようなシンボルは見つからない
     ⇒ nil

(setq sym (intern "frazzle"))  ; インターンされたシンボルを作成する
     ⇒ frazzle

(intern-soft "frazzle")        ; シンボルが見つかった!
     ⇒ frazzle

(eq sym 'frazzle)              ; そしてそれは同じシンボル
     ⇒ t

Variable: obarray: この変数はinternとreadが使用する標準のobarrayである。

Function: mapatoms function &optional obarray

この関数はオブジェクト配列obarrayの中の各シンボルにたいして、functionを一度呼び出しその後nilをリターンする。obarrayが省略されると、通常のシンボルにたいする標準のオブジェクト配列obarrayの値がデフォルトになる。

(setq count 0)
     ⇒ 0
(defun count-syms (s)
  (setq count (1+ count)))
     ⇒ count-syms
(mapatoms 'count-syms)
     ⇒ nil
count
     ⇒ 1871

mapatomsを使用する他の例については、ドキュメント文字列へのアクセスのdocumentationを参照のこと。

Function: unintern symbol obarray

この関数はオブジェクト配列obarrayからsymbolを削除する。obarrayの中にsymbolが存在ければ、uninternは何も行なわない。obarrayがnilなら現在のobarrayが使用される。

symbolにシンボルではなく文字列を与えると、それはシンボルの名前を意味する。この場合、uninternは(もしあれば)obarrayからその名前のシンボルを削除する。そのようなシンボルが存在するならuninternは何も行なわない。

uninternがシンボルを削除したらt、それ以外はnilをリターンする。

9.4 シンボルのプロパティ

シンボルはそのシンボルについての様々な情報を記録するために使用される、任意の数のシンボルプロパティー(symbol properties)をもつことができます。たとえばシンボルのrisky-local-variableプロパティーがnilなら、その変数の名前が危険なファイルローカル変数(ファイルローカル変数を参照)であることを意味します。

シンボルのプロパティーとプロパティー値はそれぞれ、シンボルのプロパティーリストセル(シンボルの構成要素を参照)に、プロパティーリスト形式(プロパティリストを参照)で格納されます。

9.4.1 シンボルのプロパティへのアクセス

以下の関数を使用してシンボルプロパティーにアクセスできます。

Function: get symbol property

この関数はsymbolのプロパティーリスト内の、名前がpropertyというプロパティーの値をリターンする。そのようなプロパティーが存在しなければnilをリターンする。したがって値がnilのときとプロパティーが存在しないときの違いはない。

名前propertyはeqを使用して既存のプロパティーと比較されるので、すべてのオブジェクトがプロパティーとして適正である。

putの例を参照のこと。

Function: put symbol property value

この関数はsymbolのプロパティーリストの、プロパティー名propertyにvalueをputして、前のプロパティー値を置き換える。put関数はvalueをリターンする。

(put 'fly 'verb 'transitive)
     ⇒'transitive
(put 'fly 'noun '(a buzzing little bug))
     ⇒ (a buzzing little bug)
(get 'fly 'verb)
     ⇒ transitive
(symbol-plist 'fly)
     ⇒ (verb transitive noun (a buzzing little bug))

Function: symbol-plist symbol: この関数はsymbolのプロパティーリストをリターンする。

Function: setplist symbol plist

この関数はsymbolのプロパティーリストをplistにセットする。plistは通常は適正なプロパティーリストであるべきだが、これは強制ではない。リターン値はplistです。

(setplist 'foo '(a 1 b (2 3) c nil))
     ⇒ (a 1 b (2 3) c nil)
(symbol-plist 'foo)
     ⇒ (a 1 b (2 3) c nil)

通常の用途には使用されない特別なobarray内のシンボルでは、非標準的な方法でプロパティーリストセルを使用することに意味があるかもしれない。実際にabbrev(abbrevとabbrev展開を参照)のメカニズムでこれを行なっている。

以下のようにsetplistとplist-putでputを定義できる:

(defun put (symbol prop value)
  (setplist symbol
            (plist-put (symbol-plist symbol) prop value)))

Function: function-get symbol property &optional autoload: この関数はgetと等価だがsymbolが関数のエイリアス名なら。実際の関数を命名するシンボルのプロパティリストを照合する点が異なる。関数の定義を参照のこと。オプション引数autoloadが非nilで、symbolが自動ロードされていれば、その自動ロードによりsymbolのpropertyがセットされるかもしれないので、この関数はそれの自動ロードを試みるだろう。autoloadがシンボルmacroなら、symbolが自動ロードされたマクロのときだけ自動ロードを試みる。

Function: function-put function property value: この関数はfunctionのpropertyにvalueをセットする。functionはシンボルであること。関数のプロパティのセットには、putよりこの関数を呼び出すほうがよい。この関数を使用すれば、いつか古いプロパティから新しいプロパティへのリマップを実装することができるからである。

9.4.2 シンボルの標準的なプロパティ

Emacsで特別な目的のために使用されるシンボルプロパティーを以下に一覧します。以下のテーブルで、“命名される関数(the named function)”と言うときは、関数名がそのシンボルであるような関数を意味します。“命名される変数(the named variable)”等の場合も同様です。

:advertised-binding: このプロパティーリストは、命名される関数のドキュメントを表示する際に優先されるキーバインディングを指定する。ドキュメント内でのキーバインディングの置き換えを参照のこと。
char-table-extra-slots: 値が非nilなら、それは命名される文字テーブル型の追加スロットの数を指定する。文字テーブルを参照のこと。
customized-face
face-defface-spec
saved-face
theme-face: これらのプロパティーはフェイスの標準のフェイス仕様(face specs)と、フォント仕様のsaved-fase、customized-face、themed-faceを記録するために使用される。これらのプロパティーを直接セットしないこと。これらのプロパティーはdeffaceと関連する関数により管理される。フェイスの定義を参照のこと。
customized-value
saved-value
standard-value
theme-value: これらのプロパティーは、カスタマイズ可能な変数のstandard-value、saved-value、customized-value(しかし保存はされない)、themed-valueを記録するために使用される。これらのプロパティーを直接セットしないこと。これらはdefcustomと関連する関数により管理される。カスタマイズ変数の定義を参照のこと。
disabled: 値が非nilなら命名される関数はコマンドとして無効になる。コマンドの無効化を参照のこと。
face-documentation: 値には命名されるフェイスのドキュメント文字列が格納される。これはdeffaceにより自動的にセットされる。フェイスの定義を参照のこと。
history-length: 値が非nilなら、命名されるヒストリーリスト変数のミニバッファーヒストリーの最大長を指定する。ミニバッファーのヒストリーを参照のこと。
interactive-form: この値は命名される関数のインタラクティブ形式である。通常はこれを直接セットするべきではない。かわりにスペシャルフォームinteractiveを使用すること。interactiveな呼び出しを参照されたい。
menu-enable: この値は命名されるメニューアイテムが、メニュー内で有効であるべきか否かを決定するための式である。単純なメニューアイテムを参照のこと。
mode-class: 値がspecialなら命名されるメジャーモードはspecial(特別)である。メジャーモードの慣習を参照のこと。
permanent-local: 値が非nilなら命名される変数はバッファーローカル変数となり、メジャーモードの変更によって変数の値はリセットされない。バッファーローカルなバインディングの作成と削除を参照のこと。
permanent-local-hook: 値が非nilなら、命名される関数はメジャーモード変更時にフック変数のローカル値から削除されない。フックのセットSetting Hooksを参照のこと。
pure: 値が非nilなら、命名される関数は副作用の影響を受けないとみなされる。定数であるような引数で呼び出される場合には、コンパイル時に評価が可能。これは実行時のエラーをコンパイル時へとシフトする。
risky-local-variable: 値が非nilなら、命名される変数はファイルローカル変数としては危険だとみなされる。ファイルローカル変数を参照のこと。
safe-function: 値が非nilなら、命名される関数は評価において一般的に安全だとみなされます。安全に関数を呼び出せるかどうかの判断を参照のこと。
safe-local-eval-function: 値が非nilなら、命名される関数はファイルローカルの評価フォーム内で安全に呼び出すことができる。ファイルローカル変数を参照のこと。
safe-local-variable: 値は命名される変数の、安全なファイルローカル値を決定する関数を指定する。ファイルローカル変数を参照のこと。
side-effect-free: 非nil値は関数の安全性(安全に関数を呼び出せるかどうかの判断を参照)、およびバイトコンパイラーの最適化を決定するために、命名される関数に副作用がないことを示す。これをセットしないこと。
variable-documentation: 非nilなら、それは命名される変数のドキュメント文字列を指定する。ドキュメント文字列はdefvarと関連する関数により自動的にセットされる。フェイスの定義を参照のこと。

10 評価

Emacs Lispでの式の評価(evaluation)は、Lispインタープリター — 入力としてLispオブジェクトを受け取り、それの式としての値(value as an expression)を計算する — により処理されます。評価を行なう方法はそのオブジェクトのデータ型に依存していて、それはこのチャプターで説明するルールにより行なわれます。インタープリターはプログラムの一部を評価するために自動的に実行されますが、Lispプリミティブ関数のevalを通じて明示的に呼び出すこともできます。

10.1 評価の概要

Lispインタープリター(またはLispエバリュエーター)はEmacsの一部であり、与えられた式の値を計算します。Lispで記述された関数が呼び出されると、エバリュエーターはその関数のbody(本文)の中の式を評価してその関数の値を計算します。したがってLispプログラムを実行するとは、実際にはLispインタープリターを実行することを意味します。

評価を意図したLispオブジェクトはフォーム(form)、または式(expression)と呼ばれます⁴。フォームはデータオブジェクトであって単なるテキストではないという事実は、Lisp風の言語と通常のプログラミング言語との間にある基本的な相違点の1つです。任意のオブジェクトを評価できますが、実際に評価される事が非常に多いのは数字、シンボル、リスト、文字列です。

以降のセクションでは、各種フォームにたいしてそれを評価することが何を意味するかの詳細を説明します。

Lispフォームを読み取ってそのフォームを評価するのは、非常に一般的なアクティビティーですが、読み取りと評価は別のアクティビティーであって、どちらか一方を単独で処理することができます。読み取っただけでは何も評価されません。読み取りはLispオブジェクトのプリント表現をそのオブジェクト自体に変換します。そのオブジェクトが評価されるべきフォームなのか、そのれともまったく違う目的をもつかを指定するのは、readの呼び出し元の役目です。入力関数を参照してください。

評価とは再帰的な処理であり、あるフォームを評価するとそのフォームの一部が評価されるといったことがよくあります。たとえば(car x)のような関数呼び出し(function call)のフォームを評価する場合、Emacsは最初にその引数(サブフォームx)を評価します。引数を評価した後、Emacsはその関数(car)を実行(executes)します。その関数がLispで記述されていれば、関数のbody(本文)を評価することによって実行が行なわれます(しかしこの例で使用しているcarはLisp関数ではなくCで実装されたプリミティブ関数である)。関数と関数呼び出しについての情報は関数を参照してください。

評価は環境(environment)と呼ばれるコンテキストの内部で行なわれます。環境はすべてのLisp変数(変数を参照)のカレント値とバインディングにより構成されます。⁵フォームが新たなバインディングを作成せずに変数を参照する際、その変数はカレントの環境から与えられる値へと評価されます。フォームの評価は、変数のバインディングによって一時的にその環境を変更することもあります(ローカル変数を参照)。

フォームの評価が永続する変更を行なうこともあります。これらの変更は副作用(side effects)と呼ばれます。副作用を生成するフォームの例は(setq foo 1)です。

コマンドキー解釈での評価と混同しないでください。エディターのコマンドループはアクティブなキーマップを使用して、キーボード入力をコマンド(インタラクティブに呼び出すことができる関数)に変換してからそのコマンドを実行するために、call-interactivelyを使用します。そのコマンドがLispで記述されていれば、そのコマンドの実行には通常は評価を伴います。しかしこのステップはコマンドキー解釈の一部とは考えません。コマンドループを参照してください。

10.2 フォームの種類

評価される事を意図したLispオブジェクトはフォーム(form)、または式(expression))と呼ばれます。Emacsがフォームを評価する方法はフォームのデータ型に依存します。Emacsは3種の異なるフォーム — シンボル、リスト、およびその他すべての型 — をもち、それらが評価される方法は異なります。このセクションではまず最初に自己評価フォームのその他の型から開始して、3つの種類をすべて1つずつ説明します。

10.2.1 自己評価を行うフォーム		自分自身を評価するフォーム。
10.2.2 シンボルのフォーム		変数として評価されるシンボル。
10.2.3 リストフォームの分類		さまざまな種類のリストフォームを区別する方法。
10.2.4 シンボル関数インダイレクション		シンボルがリストのcarにあればそのシンボルを通じて実際の関数を見つける。
10.2.5 関数フォームの評価		関数を呼び出すフォーム。
10.2.6 Lispマクロの評価		マクロを呼び出すフォーム。
10.2.7 スペシャルフォーム		スペシャルフォームは特異なプリミティブであり、それらのほとんどがとても重要である。
10.2.8 自動ロード		実際の定義を含むファイルのロードをセットアップする関数。

10.2.1 自己評価を行うフォーム

自己評価フォーム(self-evaluating form)はリストやシンボルではないすべてのフォームです。自己評価フォームはそのフォーム自身を評価します。評価の結果は評価されたオブジェクトと同じです。したがって数字の25は25、文字列"foo"は文字列"foo"に評価されます。同様にベクターの評価では、ベクターの要素の評価は発生しません — 内容が変更されずに同じベクターがリターンされます。

'123               ; 評価されずに表示される数字
     ⇒ 123

123                ; 通常どおり評価され、同じものがreturnされる
     ⇒ 123

(eval '123)        ; 手動での評価 — 同じものがreturnされる
     ⇒ 123

(eval (eval '123)) ; 2度評価しても何も変わらない。
     ⇒ 123

自己評価されるという事実による利点から数字、文字、文字列、そしてベクターでさえLispコード内で記述されるのが一般的です。しかし入力構文がない型にたいしてこれを行なうのは極めて異例です。なぜなら、これらをテキスト的に記述する方法がないからです。Lispプログラムを使用してこれらの型を含むLisp式を構築することは可能です。以下は例です:

;; バッファーオブジェクトを含む式を構築する。
(setq print-exp (list 'print (current-buffer)))
     ⇒ (print #<buffer eval.texi>)

;; それを評価する。
(eval print-exp)
     -| #<buffer eval.texi>
     ⇒ #<buffer eval.texi>

10.2.2 シンボルのフォーム

シンボルが評価されるときは変数として扱われます。それが値をもつなら結果はその変数の値になります。そのシンボルが変数としての値をもたなければ、Lispインタープリターはエラーをシグナルします。変数の使用法についての情報は変数を参照してください。

以降の例ではsetqでシンボルに値をセットしています。その後シンボルを評価してからをsetqに戻します。

(setq a 123)
     ⇒ 123

(eval 'a)
     ⇒ 123

a
     ⇒ 123

シンボルnilとtは特別に扱われるので、nilの値は常にnil、tの値は常にtになります。これらに他の値をセットしたり、他の値にバインドすることはできません。したがってこの2つのシンボルは、(たとえevalがそれらを他の任意のシンボルと同様に扱うとはいえ)自己評価フォームと同じように振る舞います。名前が‘:’で始まるシンボルも同じ方法で自己評価されます。そして、(通常は)値を変更できない点も同じです。変更不可な変数を参照してください。

10.2.3 リストフォームの分類

空ではないリストフォームは関数呼び出し、マクロ呼び出し、スペシャルフォームのいずれかで、それは1番目の引数にしたがいます。これら3種のフォームは、以下で説明するように異なる方法で評価されます。残りの要素は関数、マクロ、またはスペシャルフォームにたいする引数(arguments)を構成します。

空ではないリストを評価する最初のステップは、1番目の要素の確認です。この要素は単独でそのリストがどの種類のフォームなのかと、残りの引数をどのように処理するがを決定します。SchemeのようなLisp方言とは異なり、1番目の要素は評価されません。

10.2.4 シンボル関数インダイレクション

リストの最初の要素がシンボルなら、評価はそのシンボルの関数セルを調べて、元のシンボルの代わりに関数セルの内容を使用します。その内容が他のシンボルなら、シンボルではないものが得られるまでこのプロセスが繰り返されます。このプロセスのことをシンボル関数インダイレクション(symbol function indirection: indirectionは間接の意)と呼びます。シンボル関数インダイレクションについての情報は関数の命名を参照してください。

このプロセスの結果、シンボルの関数セルが同じシンボルを参照する場合には、無限ループを起こす可能性があります。それ以外なら最終的には非シンボルにたどりつき、それは関数か他の適切なオブジェクトである必要があります。

適切なオブジェクトとは、より正確にはLisp関数(ラムダ式)、バイトコード関数、プリミティブ関数、Lispマクロ、スペシャルフォーム、またはオートロードオブジェクトです。これらそれぞれの型については以降のセクションで説明します。これらの型以外のオブジェクトならEmacsはinvalid-functionエラーをシグナルします。

以下の例はシンボルインダイレクションのプロセスを説明するものです。わたしたちはシンボルの関数セルへの関数のセットにfset、関数セルの内容(関数セルの内容へのアクセスを参照)の取得にsymbol-functionを使用します。具体的にはfirstの関数セルにシンボルcarを格納して、シンボルfirstをersteの関数セルに格納します。

;; この関数セルのリンクを構築する:
;;   -------------       -----        -------        -------
;;  | #<subr car> | <-- | car |  <-- | first |  <-- | erste |
;;   -------------       -----        -------        -------

(symbol-function 'car)
     ⇒ #<subr car>

(fset 'first 'car)
     ⇒ car

(fset 'erste 'first)
     ⇒ first

(erste '(1 2 3))   ; ersteにより参照される関数を呼び出す
     ⇒ 1

対照的に、以下の例ではシンボル関数インダイレクションを使用せずに関数を呼び出しています。なぜなら1番目の要素はシンボルではなく、無名Lisp関数(anonymous Lisp function)だからです。

((lambda (arg) (erste arg))
 '(1 2 3))
     ⇒ 1

関数自身を実行するとその関数のbodyを評価します。ここではersteを呼び出すとき、シンボル関数インダイレクションが行なわれています。

このフォームが使用されるのは稀であり、現在では推奨されていません。かわりに以下のように記述するべきです:

(funcall (lambda (arg) (erste arg))
         '(1 2 3))

または単に

(let ((arg '(1 2 3))) (erste arg))

ビルトイン関数のindirect-functionは、明示的にシンボル関数インダイレクションを処理するための簡単な方法を提供します。

Function: indirect-function function &optional noerror

この関数はfunctionが意味するものを関数としてリターンする。functionがシンボルならfunctionの関数定義を探して、その値で最初からやり直す。functionがシンボルでなければfunction自身をリターンする。

この関数は最終的なシンボルがバインドされていなければnilをリターンする。特定のシンボル内にループがれば、この関数はcyclic-function-indirectionエラーをシグナルする。

オペション引数noerrorは廃れており、後方互換のためだけのもので効果はない。

以下はLispでindirect-functionを定義する例である:

(defun indirect-function (function)
  (if (symbolp function)
      (indirect-function (symbol-function function))
    function))

10.2.5 関数フォームの評価

リストの1番目の要素がLispの関数オブジェクト、バイトコードオブジェクト、プリミティブ関数オブジェクトのいずれかと評価されると、そのリストは関数呼び出し(function call)になります。たとえば、以下は関数+を呼び出します:

(+ 1 x)

関数呼び出しを評価する最初のステップでは、そのリストの残りの要素を左から右に評価します。結果は引数の実際の値で、リストの各要素にたいして1つの値となります。次のステップでは関数apply(関数の呼び出しを参照)を使用して、引数のリストでその関数を呼び出します。関数がLispで記述されていたら引数はその関数の引数変数にバインドするために使用されます。その後に関数body内のフォームが順番に評価されて、リストのbodyフォームの値が関数呼び出しの値になります。

10.2.6 Lispマクロの評価

リストの最初の要素がマクロオブジェクトと評価されると、そのリストはマクロ呼び出し(macro call)になります。マクロ呼び出しが評価されるとき、リストの残りの要素は最初は評価されません。そのかわりこれらの要素自体がマクロの引数に使用されます。そのマクロ定義は、元のフォームが評価される場所で置換フォームを計算します。これをマクロの展開(expansion)と言います。展開した結果は、任意の種類のフォーム — 自己評価定数、シンボル、リストになります。展開した結果自体がマクロ呼び出しなら、結果が他の種類のフォームになるまで、繰り返し展開処理が行なわれます。

通常のマクロ展開は、その展開結果を評価することにより終了します。しかし他のプログラムもマクロ呼び出しを展開し、それらが展開結果を評価するか、あるいは評価しないかもしれないので、そのマクロ展開が即時または最終的に評価される必要がない場合があります。

引数式は通常はマクロ展開の計算の一部としては評価されませんが、展開の部分として出現するので、展開結果が評価されるときに計算されます。

たとえば以下のようなマクロ定義が与えられたとします:

(defmacro cadr (x)
  (list 'car (list 'cdr x)))

(cadr (assq 'handler list))のような式はマクロ呼び出しであり、展開結果は以下のようになります:

(car (cdr (assq 'handler list)))

引数(assq 'handler list)が展開結果に含まれることに注意してください。

Emacs Lispマクロの完全な説明はマクロを参照してください。

10.2.7 スペシャルフォーム

スペシャルフォーム(special form)とは、特別だとマークされたプリミティブ関数であり、その引数のすべては評価されません。もっとも特別なフォームは制御構文の定義や変数バインディングの処理等、関数ではできないことを行ないます。

スペシャルフォームはそれぞれ、どの引数を評価して、どの引数を評価しないかについて独自のルールをもちます。特定の引数が評価されるかどうかは、他の引数を評価した結果に依存します。

式の最初のシンボルがスペシャルフォームなら、式はそのスペシャルフォームのルールにしたがう必要があります。それ以外ならEmacsの挙動は(たとえクラッシュしなくいとしても)未定義です。たとえば((lambda (x) x . 3) 4)はlambdaで始まるサブ式を含みますが、これは適正なlambda式ではないので、Emacsはエラーをシグナルするかもしれないし、3や4やnilをリターンしたり、もしかしたら他の挙動を示すかもしれません。

Function: special-form-p object: この述語は引数がスペシャルフォームかをテストして、スペシャルフォームならt、それ以外ならnilをリターンする。

以下にEmacs Lispのスペシャルフォームすべてと、それらがどこで説明されているかのリファレンスをアルファベット順でリストします。

and: see section 条件の組み合わせ
catch: see section 明示的な非ローカル脱出: catchとthrow
cond: see section 条件
condition-case: see section エラーを処理するコードの記述
defconst: see section グローバル変数の定義
defvar: see section グローバル変数の定義
function: see section 無名関数
if: see section 条件
interactive: see section interactiveな呼び出し
lambda: see section ラムダ式
let
let*: see section ローカル変数
or: see section 条件の組み合わせ
prog1
prog2
progn: see section 順序
quote: see section クォート
save-current-buffer: see section カレントバッファー
save-excursion: see section エクスカーション
save-restriction: see section ナローイング
setq: see section 変数の値のセット
setq-default: see section バッファーローカルなバインディングの作成と削除
track-mouse: see section マウスの追跡
unwind-protect: see section 非ローカル脱出
while: see section 繰り返し

Common Lispに関する注意: GNU EmacsとCommon Lispのスペシャルフォームを比較する。setq、if、catchはEmacs LispとCommon Lispの両方でスペシャルフォームである。save-excursionはEmacs Lispではスペシャルフォームだが、Common Lispには存在しない。throwはCommon Lispではスペシャルフォーム(なぜなら複数の値をthrowできなければならない)だが、Emacs Lispでは(複数の値をもたない)関数である。

10.2.8 自動ロード

オートロード(autoload)機能により、まだ関数定義がEmacsにロードされていない関数(またはマクロ)を呼び出すことができます。オートロードは定義がどのファイルに含まれるかを指定します。オートロードオブジェクトがシンボルの関数定義にある場合は、関数としてそのシンボルを呼び出すことにより、自動的に指定されたファイルがロードされます。その後にファイルからロードされた実際の定義を呼び出します。シンボル内の関数定義としてオートロードオブジェクトをアレンジする方法はautoloadで説明します。

10.3 クォート

スペシャルフォームquoteは、単一の引数を記述されたままに評価せずにリターンします。これはプログラムに自己評価オブジェクトではない、定数シンボルや定数リストを含める方法を提供します(数字、文字列、ベクターのような自己評価オブジェクトをクォートする必要はない)。

Special Form: quote object: このスペシャルフォームは評価せずにobjectをリターンする。

quoteはプログラム中で頻繁に使用されるので、Lispはそれにたいする便利な入力構文を提供します。アポストロフィー文字(‘'’)に続けてLispオブジェクト(の入力構文)を記述すると、それは1番目の要素がquote、2番目の要素がそのオブジェクトであるようなリストに展開されます。つまり入力構文'xは(quote x)の略記になります。

以下にquoteを使用した式の例をいくつか示します:

(quote (+ 1 2))
     ⇒ (+ 1 2)

(quote foo)
     ⇒ foo

'foo
     ⇒ foo

''foo
     ⇒ (quote foo)

'(quote foo)
     ⇒ (quote foo)

['foo]
     ⇒ [(quote foo)]

他のクォート構文としては、コンパイル用にLispで記述された無名のラムダ式の元となるfunction (無名関数を参照)、リストを計算して置き換える際にリストの一部だけをクォートするために使用される‘`’(バッククォートを参照)があります。

10.4 バッククォート

バッククォート構文(backquote constructs)を使用することにより、リストをクォートしてそのリストのある要素を選択的に評価することができます。もっとも簡単な使い方ではスペシャルフォームquoteと同じです (前のセクションで説明済み。クォートを参照)。たとえば以下の2つのフォームは同じ結果を生みます:

`(a list of (+ 2 3) elements)
     ⇒ (a list of (+ 2 3) elements)

'(a list of (+ 2 3) elements)
     ⇒ (a list of (+ 2 3) elements)

バッククォートする引数の内側でスペシャルマーカー‘,’を使用すると、それは値が定数でないことを示します。Emacs Lispエバリュエーターは‘,’がついた引数を放置して、リスト構文内にその値を配置します:

`(a list of ,(+ 2 3) elements)
     ⇒ (a list of 5 elements)

‘,’による置き換えを、リスト構文のより深いレベルでも使用できます。たとえば:

`(1 2 (3 ,(+ 4 5)))
     ⇒ (1 2 (3 9))

スペシャルマーカー‘,@’を使用すれば、評価された値を結果リストに継ぎ足す(splice)こともできます。継ぎ足されたリストの要素は、結果リスト内の他の要素と同じレベルになります。‘`’を使用しない等価なコードは読むのが困難なことがよくあります。以下にいくつかの例を示します:

(setq some-list '(2 3))
     ⇒ (2 3)

(cons 1 (append some-list '(4) some-list))
     ⇒ (1 2 3 4 2 3)

`(1 ,@some-list 4 ,@some-list)
     ⇒ (1 2 3 4 2 3)

(setq list '(hack foo bar))
     ⇒ (hack foo bar)

(cons 'use
  (cons 'the
    (cons 'words (append (cdr list) '(as elements)))))
     ⇒ (use the words foo bar as elements)

`(use the words ,@(cdr list) as elements)
     ⇒ (use the words foo bar as elements)

10.5 eval

フォームはほとんどの場合、実行されるプログラム内に出現することにより自動的に評価されます。ごく稀に実行時 — たとえば編集されているテキストやプロパティーリストから取得したフォームを読み取った後 — に計算されるようにフォームを評価するコードを記述する必要があるかもしれません。このようなときはeval関数を使用します。evalが不必要だったり、かわりに他の何かを使用すべきときがよくあります。たとえば変数から値を取得するにはevalも機能しますが、symbol-valueのほうが適しています。evalで評価するためにプロパティーリストに式を格納するかわりに、funcallに渡すように関数を格納した方がよいでしょう。

このセクションで説明する関数と変数はフォームの評価、評価処理の制限の指定、最後にリターンされた値の記録を行なうものです。ファイルのロードでも評価が行なわれます(ロードを参照)。

データ構造に式を格納して評価するより、データ構造に関数を格納してfuncallやapplyで呼び出すほうが、より明解で柔軟です。関数を使用することにより、引数に情報を渡す能力が提供されます。

Function: eval form &optional lexical

これは式を評価する基本的な関数である。この関数はカレント環境内でformを評価して、その結果をリターンする。formオブジェクトの型はそれが評価される方法を決定します。フォームの種類を参照のこと。

引数lexicalは、ローカル変数にたいするスコープ規則(変数のバインディングのスコーピングルールを参照)を指定する。これが省略またはnilならデフォルトのダイナミックスコープ規則を使用してformを評価することを意味する。tならレキシカルスコープ規則が使用されることを意味する。lexicalの値にはレキシカルバインディングでの特定のレキシカル環境(lexical environment)を指定する空ではないalistも指定できる。しかしこの機能はEmacs Lispデバッガーのような、特別な用途にたいしてのみ有用。レキシカルバインディングを参照のこと。

evalは関数なのでeval呼び出しに現れる引数式は2回 — evalが呼び出される前の準備で一度、eval関数自身によりもう一度 — 評価される。以下に例を示す:

(setq foo 'bar)
     ⇒ bar

(setq bar 'baz)
     ⇒ baz
;; evalが引数fooを受け取る
(eval 'foo)
     ⇒ bar
;; evalが、fooの値である、引数barを受け取る
(eval foo)
     ⇒ baz

evalで現在アクティブな呼び出しの数はmax-lisp-eval-depthに制限される(以下参照)。

Command: eval-region start end &optional stream read-function

この関数はカレントバッファー内の、位置startとendで定義されるリージョン内のフォームを評価する。この関数はリージョンからフォームを読み取ってevalを呼び出す。これはリージョンの最後に達するか、処理されないエラーがシグナルされるまで行なわれる。

デフォルトではeval-regionは出力を何も生成しない。しかしstreamが非nilなら出力関数(出力関数を参照)で生成された任意の出力、同様にリージョン内の式を評価した結果の値が、streamを使用してプリントされる。出力ストリームを参照のこと。

read-functionが非nilなら、readのかわりに1つずつ式を読み取るために使用する関数を指定すること。これは入力を読み取るストリームを指定する、1つの引数で呼び出される関数である。この関数を指定するために変数load-read-function(How Programs Do Loadingを参照)も使用できるが、引数read-functionを使用するほうが堅実である。

eval-regionはポイントを移動しない。常にnilをリターンする。

Command: eval-buffer &optional buffer-or-name stream filename unibyte print

この関数はeval-regionと似ているが、引数は異なるオプション機能を提供する。eval-bufferはバッファーbuffer-or-nameのアクセス可能な部分(Narrowing in The GNU Emacs Manualを参照)の全体を処理する。buffer-or-nameにはバッファー名(文字列)を指定でき、nil(または省略)のときはカレントバッファーを意味する。streamが非nil、またはprintがnilなら、eval-regionのようにstreamが使用される。この場合には式の評価結果の値は依然として破棄されるが、出力関数による出力はエコーエリアにプリントされる。filenameはload-history (アンロードを参照)に使用されるファイル名であり、デフォルトはbuffer-file-name (バッファーのファイル名を参照)。unibyteが非nilならread可能な限りは文字列をユニコードに変換する。

eval-current-bufferはこのコマンドのエイリアスである。

User Option: max-lisp-eval-depth

この変数はエラー(エラーメッセージは"Lisp nesting exceeds max-lisp-eval-depth")がシグナルされる前にeval、apply、funcallの呼び出しで許容される最大の深さを定義する。

制限を超過時のエラーを付随するこの制限は、誤って定義された関数による無限再帰をEmacs Lispが回避する方法の1つである。max-lisp-eval-depthの値を過大に増加させると、そのようなコードはかわりにスタックオーバーフローを起こすだろう。オーバーフローを処理できるシステムがいくつかある。この場合には通常のLisp評価は割り込まれて、制御はトップレベルのコマンドループ(top-level)に戻される。この状況ではEmacs Lispデバッガにエンターする手段は存在しないことに注意されたい。エラーによるデバッガへのエンターを参照のこと。

Lisp式に記述された関数の呼び出し、関数呼び出しの引数と関数bodyフォームにたいする再帰評価、Lispコード内での明示的な呼び出し等では内部的にeval、apply、funcallを使用して深さ制限を計数する。

The default value of this variable is 800. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute.

max-specpdl-sizeはネストの他の制限を提供する。Local Variablesを参照のこと。

Variable: values

この変数の値は読み取り、評価、プリントを行なった標準的なEmacsコマンドにより、バッファー(ミニバッファーを含む)からリターンされる値のリストである(これには*ielm*バッファーでの評価や、lisp-interaction-modeでのC-jやC-x C-e、類似の評価コマンドを使用した評価は含まれないことに注意)。要素の順番はもっとも最近のものが最初になる。

(setq x 1)
     ⇒ 1

(list 'A (1+ 2) auto-save-default)
     ⇒ (A 3 t)

values
     ⇒ ((A 3 t) 1 …)

この変数は最近評価されたフォームの値を後で参照するのに有用。values自体の値のプリントは、値がおそらく非常に長くなるので通常は悪いアイデアである。かわりに以下のように特定の要素を調べること:

;; もっとも最近評価された結果を参照する
(nth 0 values)
     ⇒ (A 3 t)

;; これは新たな要素をputするので
;;   すべての要素が1つ後に移動する
(nth 1 values)
     ⇒ (A 3 t)

;; これは次に新しい、この例の前の次に新しい要素を取得する
(nth 3 values)
     ⇒ 1

11 制御構造

Lispプログラムは一連の式、あるいはフォーム (フォームの種類を参照)により形成されます。これらのフォームの実行順は制御構造(control structures)で囲むことによって制御します。制御構造とはその制御構造が含むフォームをいつ、どのような条件で、何回実行するかを制御するスペシャルフォームです。

もっとも単純な実行順は1番目はa、2番目はb、...というシーケンシャル実行(sequential execution: 順番に実行)です。これは関数のbody内の連続する複数のフォームや、Lispコードのファイル内のトップレベルを記述したときに発生します — つまりフォームは記述した順に実行されます。わたしたちはこれをテキスト順(textual order)と呼びます。たとえば関数のbodyが2つのフォームaとbから構成される場合、関数の評価は最初にa、次にbを評価します。bを評価した結果がその関数の値となります。

明示的に制御構造を使用することにより、非シーケンシャルな順番での実行が可能になります。

Emacs Lispは他の様々な順序づけ、条件、繰り返し、(制御された)ジャンプを含む複数の種類の制御構造を提供しており、以下ではそれらのすべてを記述します。ビルトインの制御構造は制御構造のサブフォームが評価される必要がなかったり、順番に評価される必要がないのでスペシャルフォームです。独自の制御構造を構築するためにマクロを使用することができます(マクロを参照)。

11.1 順序

フォームを出現順に評価するのは、あるフォームから別のフォームに制御を渡すもっとも一般的な制御です。関数のbodyのようなコンテキストにおいては自動的にこれが行なわれます。他の場所ではこれを行なうために制御構造を使用しなければなりません。Lispで一単純な制御構造はprognです。

スペシャルフォームprognは以下のようなものです:

(progn a b c …)

これは順番にa、b、c、...を実行するよう指定します。これらはprognフォームのbodyと呼ばれます。body内の最後のフォームの値がprogn全体の値になります。(progn)はnilをリターンします。

初期のLispではprognは、連続で複数のフォームを実行して最後のフォームの値を使用する唯一の方法でした。しかしプログラマーは関数のbodyの、(その時点では)1つのフォームだけが許される場所でprognを使用する必要が多いことに気づきました。そのため関数のbodyを暗黙のprognにして、prognのbodyのように複数のフォームを記述できるようにしました。他の多くの制御構造も暗黙のprognを同様に含みます。結果として昔ほどprognは多用されなくなりました。現在ではprognが必要になるのはunwind-protect、and、or、またはifのthenパートの中であることがほとんどです。

Special Form: progn forms…

このスペシャルフォームはformsのすべてをテキスト順に評価してフォームの結果をリターンする。

(progn (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
⇒ "The third form"

他の2つの構文は一連のフォームを同様に評価しますが、異なる値をリターンします:

Special Form: prog1 form1 forms…

このスペシャルフォームはform1とformsのすべてをテキスト順に評価してform1の結果をリターンする。

(prog1 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
⇒ "The first form"

以下の例は変数xのリストから1番目の要素を削除して、削除した1番目の要素の値をリターンする:

(prog1 (car x) (setq x (cdr x)))

Special Form: prog2 form1 form2 forms…

このスペシャルフォームはform1、form2、その後のformsのすべてをテキスト順で評価してform2の結果をリターンする。

(prog2 (print "The first form")
       (print "The second form")
       (print "The third form"))
     -| "The first form"
     -| "The second form"
     -| "The third form"
⇒ "The second form"

11.2 条件

条件による制御構造は選択肢の中から選択を行ないます。Emacs Lispには4つの条件フォームをもちます。ifは他の言語のものとほとんど同じです。whenとunlessはifの変種です。condは一般化されたcase命令です。

Special Form: if condition then-form else-forms…

ifはconditionの値にもとづきthen-formとelse-formsを選択する。評価されたconditionが非nilならthen-formが評価されて結果がリターンされる。それ以外ならelse-formsがテキスト順に評価されて最後のフォームの値がリターンされる(ifのelseパートは暗黙のprognの例である。順序を参照)。

conditionの値がnilでelse-formsが与えられなければ、ifはnilをリターンする。

選択されなかったブランチは決して評価されない — 無視される — ので、ifはスペシャルフォームである。したがって以下の例ではprintが呼び出されることはないのでtrueはプリントされない。

(if nil
    (print 'true)
  'very-false)
⇒ very-false

Macro: when condition then-forms…

これはelse-formsがなく、複数のthen-formsが可能なifの変種である。特に、

(when condition a b c)

は以下と完全に等価である

(if condition (progn a b c) nil)

Macro: unless condition forms…

これはthen-formがないifの変種です:

(unless condition a b c)

は以下と完全に等価である

(if condition nil
   a b c)

Special Form: cond clause…

condは任意個数の選択肢から選択を行なう。cond内の各clauseはリストでなければならない。このリストのCARはconditionで、(もしあれば)残りの要素はbody-formsとなる。したがってclauseは以下のようになる:

(condition body-forms…)

condは各clauseのconditionを評価することにより、テキスト順でclauseを試みる。conditionの値が非nilならそのclauseは成り立つ。その後にcondはそのclauseのbody-formsを評価して、body-formsの最後の値をリターンする。残りのclauseは無視される。

conditionの値がnilならそのclauseは失敗して、condは次のclauseに移動してそれのconditionを試みる。

clauseは以下のようにも見えるかもしれない:

(condition)

conditionがテストされたときに非nilなら、condフォームはconditionの値をリターンする。

すべてのconditionがnilに評価された場合 — つまりすべてのclauseが不成立なら、condはnilをリターンする。

以下の例はxの値が数字、文字列、バッファー、シンボルなのかをテストする4つのclauseをもつ:

(cond ((numberp x) x)
      ((stringp x) x)
      ((bufferp x)
       (setq temporary-hack x) ; 1つのclauseに
       (buffer-name x))        ; 複数bodyフォーム
      ((symbolp x) (symbol-value x)))

前のclauseが不成立のとき最後の条項を実行したいときがよくある。これを行なうには(t body-forms)のように、conditionの最後のclauseにtを使用する。フォームtはtに評価され決してnilにならないので、このclauseが不成立になることはなく最終的にcondはこのclauseに到達する。たとえば:

(setq a 5)
(cond ((eq a 'hack) 'foo)
      (t "default"))
⇒ "default"

このcond式はaの値がhackならfoo、それ以外は文字列"default"をリターンする。

すべての条件構文はcondかifのいずれかで表すことができます。したがってどちらを選択するかはスタイルの問題になります。たとえば:

(if a b c)
≡
(cond (a b) (t c))

11.2.1 パターンマッチングによるcase文

condフォームにより、あらかじめ記述された既知の特定の値と式の値を比較する述語条件を使用して選択肢を選択できます。しかし広範な値クラス間を区別する、より一般的な条件にもとづいて選択肢を選択するのが有用なこともあります。pcaseマクロにより、一連のパターンにたいする式の値のマッチングにもとづいて選択肢を選択できます。パターンにはリテラル値(condで使用した比較用のリテラル値)や、予想される式の値のより一般的な構造記述を使用できます。

Macro: pcase expression &rest clauses

Evaluate expression and choose among an arbitrary number of alternatives based on the value of expression. The possible alternatives are specified by clauses, each of which must be a list of the form (pattern body-forms…). pcase tries to match the value of expression to the pattern of each clause, in textual order. If the value matches, the clause succeeds; pcase then evaluates its body-forms, and returns the value of the last of body-forms. Any remaining clauses are ignored. If no clauses match, then the pcase form evaluates to nil.

patternパートはバッククォートでクォートされたQPatternと、クォートされていないUPatternのいずれかで指定できる。UPatternsのほうが単純なのでそれから説明する。

注意: 以下のパターンの記述ではpcaseの1つ目の引数となるexpressionの値を参照するために、“マッチされる値”という言葉を使用している。

UPatternには以下の形式を指定できる:

'val: マッチされる値がvalとequalならマッチ。
atom: 任意のatom (キーワード、数字、文字列)にマッチする(これらは自己クォートされるのでこの種のUPatternは実際には'atomの略記である)。文字列(浮動小数点数)は同じ内容(値)の任意の文字列(浮動小数点数)とマッチすることに注意。
_: 任意の値にマッチする。これはdon’t careやwildcardとして知られる。
symbol: 任意の値にマッチする。さらにマッチした値をsymbolにletバインドするので、body-formsや後続のパターンからそれを参照することができる。
(pred predfun): マッチされる値を引数として述語関数predfunを呼び出して、非nilをリターンしたらマッチ。predfunは後述するフォームのいずれかを指定できる。
(guard boolean-expression): boolean-expressionが非nilに評価されたらマッチ。これにより以前のUPatternで、値(マッチされる値を含む)にバインドされたシンボルを参照するブール条件をUPatternに含めることができる。典型的にはUPattern and内で使用される(以下参照)。たとえば(and x (guard (< x 10)))は10より小さい任意の数にマッチして、その数を変数xにletバインドする。
(let upattern expression): 指定されたexpressionが指定されたupatternにマッチしたらマッチ。これによりpcaseの1つ目の引数だけでなく、任意の式の値にパターンをマッチできる(upatternはUPattern symbolを使用してシンボルを値にバインドできるのでletと呼ばれる。たとえば((or `(key . ,val) (let val 5)) val))。
(app function upattern): Matches if function applied to the value being matched returns a value that matches upattern. This is like the pred UPattern, except that it tests the result against upattern, rather than against a boolean truth value. The function call can use one of the forms described below.
(or upattern1 upattern2…): 引数のUPatternのいずれかがマッチしたらマッチ。マッチする最初のUPatternが見つかったら残りはテストされない。この理由により、マッチされる値にシンボルをletバインドするすべてのUPatternは同じシンボルをバインドすること。
(and upattern1 upattern2…): 引数のUPatternすべてがマッチしたらマッチ。

predとappのUPatternで使用される関数呼び出しは、以下のいずれかのフォームをもつことができる:

integerpのような関数シンボル: この場合には、その名前つき関数がマッチされる値に適用される。
ラムダ関数 (lambda (arg) body): この場合には、そのラムダ関数がマッチされる値を単一の引数として呼び出される。
(func args…): これは指定されたn個の引数で呼び出される関数である。関数はこれらn個の引数と、マッチされる値であるn+1番目の引数を追加して呼び出される。

以下はUPatternを使用した説明用の例です:

(pcase (get-return-code x)
  ('success       (message "Done!"))
  ('would-block   (message "Sorry, can't do it now"))
  ('read-only     (message "The shmliblick is read-only"))
  ('access-denied (message "You do not have the needed rights"))
  (code           (message "Unknown return code %S" code)))

加えてより協力なバッククォートされたパターンを使用できます。これらを使用すればpcaseの1つ目の引数の式の値を、その構造(structure)の仕様とマッチさせることができます。たとえば1つ目の要素が特定の文字列で、2つ目の要素が`("first" ,second-elem)のようなバッククォートされた任意の値であるような2要素のリストを、値として強制指定することができます。

バッククォートされたパターンは`qpatternという形式をもち、qpatternは以下の形式をもつことができます:

(qpattern1 . qpattern2): マッチされる値が、carがqpattern1、cdrがqpattern2にマッチするようなコンスセルならマッチ。これは(qpattern1 qpattern2 …)のように、容易にバッククォートされたリストに一般化できる。
[qpattern1 qpattern2 … qpatternm]: マッチされる値が、長さmで0から(m-1)番目の要素がそれぞれqpattern1、qpattern2、…、qpatternmにマッチするようなベクターならマッチ。
atom: マッチされる値の対応する要素が指定されたatomとequalならマッチ。
,upattern: マッチされる値の対応する要素が指定されたupatternとマッチすればマッチ。

QPatternは後述のpcase-defmacroを使用してUPatternのトップレベルで実装されているので、QPatternの使用はUPatternを使用することでのみ表現可能なことに注意。とはいえQPatternの使用により、多くの場合コードの可読性は向上するだろう。

以下はpcaseを使用して、小さな式言語用のシンプルなインタープリターを実装する例です(この例にはレキシカルバインディングが必要なことに注意。)レキシカルバインディングを参照のこと):

(defun evaluate (exp env)
  (pcase exp
    (`(add ,x ,y)       (+ (evaluate x env) (evaluate y env)))
    (`(call ,fun ,arg)  (funcall (evaluate fun env) (evaluate arg env)))
    (`(fn ,arg ,body)   (lambda (val)
                          (evaluate body (cons (cons arg val) env))))
    ((pred numberp)     exp)
    ((pred symbolp)     (cdr (assq exp env)))
    (_                  (error "Unknown expression %S" exp))))

ここで`(add ,x ,y)は、expがリテラルシンボルaddで始まる3要素のリストであることをチェックしてから、2つ目と3つ目の要素を抽出して変数xとyにバインドするパターンです。それからxとyを評価して結果を加算します。同様にcallとfnのパターンは、関数呼び出しに相当するものを2つ実装します。(pred numberp)はexpが数であるかをチェックして、もしそうならそれを評価します。(pred symbolp)はシンボルにマッチして、その連想をリターンします。最後に_はすべてにマッチするcatch-allパターンなので、構文エラーの報告に適しています。

以下は評価した結果を含む、この小さな言語のサンプルプログラムの例です:

(evaluate '(add 1 2) nil)                 ;=> 3
(evaluate '(add x y) '((x . 1) (y . 2)))  ;=> 3
(evaluate '(call (fn x (add 1 x)) 2) nil) ;=> 3
(evaluate '(sub 1 2) nil)                 ;=> error

pcase-defmacroを使用することにより追加のUPatternを定義できます。

Macro: pcase-defmacro name args &rest body: pcaseにたいして新たな種類のUPatternを定義する。新たなUPatternは(name actual-args)のように呼び出されるだろう。bodyには、UPattern nameを他の何らかのUPatternに書き換える方法を記述すること。argsがactual-argsにバインドされる環境でbodyを評価した結果がこの書き換えとなる。

11.3 条件の組み合わせ

このセクションでは複雑な条件を表現するためにifやcondとともによく使用される3つの構文を説明します。andとorの構文は、ある種の複数条件の構文として個別に使用することもできます。

Function: not condition: この関数はconditionが偽であることをテストする。この関数はconditionがnilならt、それ以外はnilをリターンする。関数notはnullと等価であり、空のリストをテストする場合はnullの使用を推奨する。

Special Form: and conditions…

スペシャルフォームandは、すべてのconditionsが真かどうかをテストする。この関数はconditionsを記述順に1つずつ評価することにより機能する。

あるconditionsがnilに評価されると、残りのconditionsに関係なく、andはnilをリターンしなければならない。この場合andは即座にnilをリターンして、残りのconditionsは無視される。

すべてのconditionsが非nilなら、それらの最後の値がandフォームの値になる。conditionsがない単独の(and)はtをリターンする。なぜならすべてのconditionsが非nilとなるので、これは適切である(考えてみてみよ、非nilでないconditionsはどれか?)。

以下に例を示す。1番目の条件は整数1をリターンし、これはnilではまい。同様に2番目の条件は整数2をリターンし、これもnilではない。3番目の条件はnilなので、のこりの条件が評価されることは決してない。

(and (print 1) (print 2) nil (print 3))
     -| 1
     -| 2
⇒ nil

以下はandを使用した、より現実的な例である:

(if (and (consp foo) (eq (car foo) 'x))
    (message "foo is a list starting with x"))

(consp foo)がnilをリターンすると、(car foo)は実行されないのでエラーにならないことに注意。

ifかcondのいずれかを使用して、and式を記述することもできる。以下にその方法を示す:

(and arg1 arg2 arg3)
≡
(if arg1 (if arg2 arg3))
≡
(cond (arg1 (cond (arg2 arg3))))

Special Form: or conditions…

スペシャルフォームorは、少なくとも1つのconditionsが真かどうかをテストする。この関数はすべてのconditionsを1つずつ、記述された順に評価することにより機能する。

あるconditionsが非nil値に評価されたら、orの結果は非nilでなければならない。この場合orは即座にリターンし、残りのconditionsは無視される。この関数がリターンする値は、非nil値に評価された条件の値そのものである。

すべてのconditionsがnilなら、or式はnilをリターンします。conditionsのない単独の(or)はnilをリターンする。なぜならすべてのconditionsがnilになるのでこれは適切である(考えてみよ、nilでないconditionsはどれか?)。

たとえば以下の式は、xがnilか整数0かどうかをテストする:

(or (eq x nil) (eq x 0))

and構文と同様に、orをcondに置き換えて記述することができる。たとえば:

(or arg1 arg2 arg3)
≡
(cond (arg1)
      (arg2)
      (arg3))

ほとんどの場合は、orをifに置き換えて記述できるが完全ではない:

(if arg1 arg1
  (if arg2 arg2
    arg3))

これは完全に同一ではない。なぜならarg1かarg2を2回評価するかもしれないからである。対照的に(or arg1 arg2 arg3)が2回以上引数を評価することは決してない。

11.4 繰り返し

繰り返し(iteration)とは、プログラムの一部を繰り返し実行することを意味します。たとえばリストの各要素、または0からnの整数にたいして、繰り返し一度ずつ何らかの計算を行いたいとしましょう。Emacs Lispではスペシャルフォームwhileでこれを行なうことができます:

Special Form: while condition forms…

whileは最初にconditionを評価する。結果が非nilならformsをテキスト順に評価する。その後にconditionを再評価して結果が非nilなら、再度formsを評価する。この処理はconditionがnilに評価されるまで繰り返される。

繰り返し回数に制限はない。このループはconditionがnilに評価されるか、エラーになるか、またはthrowで抜け出す(非ローカル脱出を参照)まで継続される。

whileフォームの値は常にnilである。

(setq num 0)
     ⇒ 0

(while (< num 4)
  (princ (format "Iteration %d." num))
  (setq num (1+ num)))
     -| Iteration 0.
     -| Iteration 1.
     -| Iteration 2.
     -| Iteration 3.
     ⇒ nil

各繰り返しごとに何かを実行して、その後も終了テストを行なうrepeat-untilループを記述するには、以下のようにwhileの1番目の引数としてbodyの後に終了テストを記述して、それをprognの中に配置する:

(while (progn
         (forward-line 1)
         (not (looking-at "^$"))))

これは1行前方に移動して、空行に達するまで行単位の移動を継続する。独特な点はwhileがbodyをもたず、終了テスト(これはポイント移動という実処理も行なう)だけを行うことである。

マクロdolistおよびdotimesは、2つの一般的な種類のループを記述する、便利な方法を提供します。

Macro: dolist (var list [result]) body…

この構文はlistの各要素に一度bodyを実行して、カレント要素をローカルに保持するように、変数varにバインドする。その後にresultを評価した値、resultが省略された場合はnilをリターンする。たとえば以下はreverse関数を定義するためにdolistを使用する方法の例である:

(defun reverse (list)
  (let (value)
    (dolist (elt list value)
      (setq value (cons elt value)))))

Macro: dotimes (var count [result]) body…

この構文は0以上count未満の各整数にたいして、一度bodyを実行してから、繰り返しのカレント回数となる整数を変数varにバインドする。その後にresultの値、resultが省略された場合はnilをリターンする。以下はdotimesを使用して、何らかの処理を100回行なう例である:

(dotimes (i 100)
  (insert "I will not obey absurd orders\n"))

11.5 Generators

ジェネレーター(generator)とは、潜在的に無限な値ストリームを生成する関数です。毎回その関数が値を生成するごとに、呼び出し側が次の値を要求するまで、自身をサスペンドします。

Macro: iter-defun name args [doc] [declare] [interactive] body…

iter-defunはジェネレーター関数を定義する。ジェネレーター関数は通常の関数と同様のsignatureをもつが、異なるように機能する。ジェネレーター関数は呼び出し時にbodyを実行するのではなく、かわりにiteratorオブジェクトをリターンする。このiteratorは値を生成するためにbodyを実行、値を発行するとiter-yieldかiter-yield-fromが出現するまで一時停止する。bodyが正常にリターンした際に、iter-nextがコンディションデータとなるbodyの結果とともに、iter-end-of-sequenceをシグナルする。

body内部では任意の種類のLispコードが有効だが、iter-yieldとiter-yield-fromはunwind-protectフォームの内部にあってはならない。

Macro: iter-lambda args [doc] [interactive] body…: iter-lambdaはiter-defunで生成されたジェネレーター関数と同様な、無名のジェネレーター関数を生成する。

Macro: iter-yield value: iter-yieldがジェネレーター関数内部で出現した際には、カレントiteratorが一時停止してiter-nextからvalueをリターンすることを示す。iter-yieldは、次回iter-next呼び出しのvalueパラメーターへと評価される。

Macro: iter-yield-from iterator: iter-yield-fromはiteratorが生成するすべての値を生成して、そのiteratorのジェネレーター関数が通常リターンする値へと評価される。これが制御を得ている間、iteratorはiter-nextを使用して送信された値を受け取る。

ジェネレーター関数を使用するには、まずそれを普通に呼び出してiteratorオブジェクトを生成します。iteratorはジェネレーターの固有のインスタンスです。その後でこのiteratorから値を取得するためにiter-nextを使用します。iteratorから取得する値がなくなると、iter-nextはそのiteratorの最終値とともにiter-end-of-sequenceのコンディションをraisesします。

ジェネレーター関数のbodyは、iter-nextの呼び出しの内側でのみ実行されることに注意することが重要です。iter-defunで定義された関数の呼び出しはiteratorを生成します。何か興味があることが発生したら、iter-nextでこのiteratorを制御しなければなりません。ジェネレーター関数の個々の呼び出しは、それぞれが独自に状態をもつ別個のiteratorを生成します。

Function: iter-next iterator value

iteratorから次の値を取得する。(iteratorのジェネレーター関数がリターンしていて)生成される値が存在しない場合、iter-nextはコンディションiter-end-of-sequenceをシグナルする。このコンディションに関連付けられるデータ値は、iteratorのジェネレーター関数がリターンした値である。

valueはiteratorに送信されて、iter-yieldを評価した値になる。iteratorのジェネレーター関数の開始時には、ジェネレーター関数はiter-yieldフォームを何も評価していないので、与えられたiteratorにたいする最初のiter-next呼び出しではvalueは無視される。

Function: iter-close iterator: iteratorがunwind-protectのbodyformフォーム内でサスペンドされていたら、ガーベージコレクション処理後にEmacsが最終的にunwindハンドラーを実行する(unwind-protectのunwindforms内部ではiter-yieldは不当であることに注意)。その前に確実にこれらのハンドラーを実行するには、iter-closeを使用すること。

iteratorを簡単に連携できるように、便利な関数がいくつか提供されています:

Macro: iter-do (var iterator) body …: iteratorが生成する各値をvarにバインドしつつbodyを実行する。

Common Lispのループ機能にもiteratorと連携する機能が含まれます。Loop Facility in Common Lisp Extensionsを参照してください。

以下のコード片はiteratorとの連携における重要な原則を示すものです。

(require 'generator)
(iter-defun my-iter (x)
  (iter-yield (1+ (iter-yield (1+ x))))
   ;; Return normally
  -1)

(let* ((iter (my-iter 5))
       (iter2 (my-iter 0)))
  ;; 6をプリント
  (print (iter-next iter))
  ;; 9をプリント
  (print (iter-next iter 8))
  ;; 1をプリント
  ;; iterとiterは異なる状態をもつ
  (print (iter-next iter2 nil))

  ;; ここでiterシーケンスの終了を待機
  (condition-case x
      (iter-next iter)
    (iter-end-of-sequence
      ;; my-iterが通常の方法でリターンした-1をプリント
      (print (cdr x)))))

11.6 非ローカル脱出

非ローカル脱出(nonlocal exit)とは、プログラム内のある位置から別の離れた位置へ制御を移します。Emacs Lispではエラーの結果として非ローカル脱出が発生することがあります。明示的な制御の下で非ローカル脱出を使用することもできます。非ローカル脱出は脱出しようとしている構文により作成された、すべての変数バインディングのバインドを解消します。

11.6.1 明示的な非ローカル脱出: `catch`と`throw`

ほとんどの制御構造は、その構文自身の内部の制御フローだけに影響します。関数throwは、この通常のプログラム実行でのルールの例外です。これはリクエストにより非ローカル脱出を行ないます(他にも例外はあるがそれらはエラー処理用のものだけ)。throwはcatchの内部で使用され、catchに制御を戻します。たとえば:

(defun foo-outer ()
  (catch 'foo
    (foo-inner)))

(defun foo-inner ()
  …
  (if x
      (throw 'foo t))
  …)

throwフォームが実行されると、対応するcatchに制御を移して、catchは即座にリターンします。throwの後のコードは実行されません。throwの2番目の引数はcatchのリターン値として使用されます。

関数throwは1番目の引数にもとづいて、それにマッチするcatchを探します。throwは1番目の引数が、throwで指定されたものとeqであるようなcatchを検索します。複数の該当するcatchがある場合には、最内のものが優先されます。したがって上記の例ではthrowがfooを指定していて、foo-outer内のcatchが同じシンボルを指定しているので、(この間に他のマッチするcatchは存在しないと仮定するなら)そのcatchが該当します。

throwの実行により、マッチするcatchまでのすべてのLisp構文(関数呼び出しを含む)を脱出します。この方法によりletや関数呼び出しのようなバインディング構文を脱出する場合には、これらの構文を正常にexitしたときのように、そのバインディングは解消されます(ローカル変数を参照)。同様にthrowはsave-excursion(エクスカーションを参照)によって保存されたバッファーと位置を復元します。throwがスペシャルフォームunwind-protectを脱出した場合には、unwind-protectにより設定されたいくつかのクリーンアップも実行されます。

ジャンプ先となるcatch内にレキシカル(局所的)である必要はありません。throwはcatch内で呼び出された別の関数から、同じようにに呼び出すことができます。throwが行なわれたのが、時系列的にcatchに入った後で、かつexitする前である限り、そのthrowはcatchにアクセスできます。エディターのコマンドループから戻るexit-recursive-editのようなコマンドで、throwが使用されるのはこれが理由です。

Common Lispに関する注意: Common Lispを含む、他のほとんどのバージョンのLispは非シーケンシャルに制御を移すいくつかの方法 — たとえばreturn、return-from、go — をもつ。Emacs Lispはthrowのみ。cl-libライブラリーはこれらのうちいくつかを提供する。Blocks and Exits in Common Lisp Extensionsを参照のこと。

Special Form: catch tag body…

catchはthrow関数にたいするリターン位置を確立する。リターン位置はtagにより、この種の他のリターン位置と区別される。tagはnil以外の任意のLispオブジェクト。リターン位置が確立される前に、引数tagは通常どおり評価される。

リターン位置が効果をもつことにより、catchはbodyのフォームをテキスト順に評価する。フォームが(エラーや非ローカル脱出なしで)通常に実行されたなら、bodyの最後のフォームの値がcatchからリターンされる。

bodyの実行の間にthrowが実行された場合、tagと同じ値を指定するとcatchフォームは即座にexitする。リターンされる値は、それが何であれthrowの2番目の引数に指定された値である。

Function: throw tag value

throwの目的は、以前にcatchにより確立されたリターン位置に戻ることである。引数tagは、既存のさまざまなリターン位置からリターン位置を選択するために使用される。複数のリターン位置がtagにマッチしたら、最内のものが使用される。

引数valueはcatchからリターンされる値として使用される。

タグtagのリターン位置が存在しなければ、データ(tag value)とともにno-catchエラーがシグナルされます。

11.6.2 `catch`と`thrown`の例

2重にネストされたループから脱出する1つの方法は、catchとthrowを使うことです(これはほとんどの言語ではgotoにより行なわれるだろう)。ここではiとjを0から9に変化させて、(foo i j)を計算します:

(defun search-foo ()
  (catch 'loop
    (let ((i 0))
      (while (< i 10)
        (let ((j 0))
          (while (< j 10)
            (if (foo i j)
                (throw 'loop (list i j)))
            (setq j (1+ j))))
        (setq i (1+ i))))))

fooが非nilをリターンしたら即座に処理を中止して、iとjのリストをリターンしています。fooが常にnilをリターンする場合には、catchは通常どおりリターンして、その値はwhileの結果であるnilとなります。

以下では2つのリターン位置を一度に表す、微妙に異なるトリッキーな例を2つ示します。まず同じタグhackにたいして2つのリターン位置があります:

(defun catch2 (tag)
  (catch tag
    (throw 'hack 'yes)))
⇒ catch2

(catch 'hack
  (print (catch2 'hack))
  'no)
-| yes
⇒ no

どちらのリターン位置もthrowにマッチするタグをもつので内側のもの、つまりcatch2で確立されたcatchへgotoします。したがってcatch2は通常どおり値yesをリターンして、その値がプリントされます。最後に外側のcatchの2番目のbody、つまり'noが評価されて外側のcatchからそれがリターンされます。

ここでcatch2に与える引数を変更してみましょう:

(catch 'hack
  (print (catch2 'quux))
  'no)
⇒ yes

この場合も2つのリターン位置がありますが、今回は外側だけがタグhackで、内側はかわりにタグquuxをもちます。したがってthrowにより、外側のcatchが値yesをリターンします。関数printが呼び出されることはなくbodyのフォーム'noも決して評価されません。

11.6.3 エラー

Emacs Lispが何らかの理由で評価できないようなフォームの評価を試みると、エラー(error)がシグナル(signal)されます。

エラーがシグナルされるとエラーメッセージを表示して、カレントコマンドの実行を終了するのがEmacsデフォルトの反応です。たとえばバッファーの最後でC-fとタイプしたときのように、ほとんどの場合にはこれは正しい反応になります。

複雑なプログラムでは単なる終了が望ましくない場合もあるでしょう。たとえばそのプログラムがータ構造に一時的に変更を行なっていたり、プログラム終了前に削除する必要がある一時バッファーを作成しているかもしれません。このような場合には、エラー時に評価されるクリーンアップ式(cleanup expressions)を設定するために、unwind-protectを使用するでしょう(非ローカル脱出のクリーンアップを参照)。サブルーチン内のエラーにもかかわらずに、プログラムの実行を継続したいときがあるかもしれません。このような場合には、エラー時のリカバリーを制御するエラーハンドラー(error handlers)を設定するためにcondition-caseを使用するでしょう。

エラーハンドラーを使用せずにプログラムの一部から別の部分へ制御を移すためには、catchとthrowを使用します。明示的な非ローカル脱出: catchとthrowを参照してください。

11.6.3.1 エラーをシグナルする方法

エラーのシグナリング(signaling)とは、エラーの処理を開始することを意味します。エラー処理は通常は実行中のプログラムのすべて、または一部をアボート(abort)してエラーをハンドルするためにセットアップされた位置にリターンします。ここではエラーをシグナルする方法を記述します。

ほとんどのエラーは、たとえば整数にたいしてCARの取得を試みたり、バッファーの最後で1文字前方に移動したときなどのように、他の目的のために呼び出したLispプリミティブ関数の中で自動的にシグナルされます。関数errorとsignalで明示的にエラーをシグナルすることもできます。

ユーザーがC-gをタイプしたときに発生するquitはエラーとは判断されませんが、ほとんどはエラーと同様に扱われます。quitを参照してください。

すべてのエラーメッセージはそれぞれ、何らかのエラーメッセージを指定します。そのメッセージは何が悪いのか(“File does not exist”)、物事がどうしてそうあるべきではない(“File must exist”)かを示すべきです。Emacs Lispの慣習ではエラーメッセージは大文字で開始され、区切り文字で終わるべきではありません。

Function: error format-string &rest args

この関数はformat-stringとargsにたいして、format-message (文字列のフォーマットを参照)を適用して構築されたエラーメッセージとともに、エラーをシグナルする。

以下はerrorを使用する典型的な例である:

(error "That is an error -- try something else")
     error→ That is an error -- try something else

(error "Invalid name `%s'" "A%%B")
     error→ Invalid name ‘A%%B’

2つの引数 — エラーシンボルerrorとformat-messageがリターンするる文字列を含むリスト — でsignalを呼び出すことによりerrorは機能する。

警告: エラーメッセージとして固定の文字列を使用したい場合、単に(error string)とは記述しないこと。もしstringが‘%’、‘`’、‘'’を含んでいると、再フォーマットされて望む結果は得られないだろう。かわりに、(error "%s" string)を使用すること。

Function: signal error-symbol data

この関数はerror-symbolで命名されるエラーをシグナルする。引数dataはエラー状況に関連する追加のLispオブジェクトのリスト。

引数error-symbolはエラーシンボル(error symbol) — define-errorで定義されたシンボル — でなければならない。これはEmacs Lispが異なる種類のエラーをクラス分けする方法である。エラーシンボル(error symbol)、エラーコンディション(error condition)、コンディション名(condition name)の説明についてはエラーシンボルとエラー条件を参照のこと。

エラーが処理されない場合には、エラーメッセージをプリントするために2つの引数が使用される。このエラーメッセージは通常、error-symbolのerror-messageプロパティーにより提供される。dataが非nilなら、その後にコロンとdataの未評価の要素をカンマで区切ったリストが続く。errorにたいするエラーメッセージはdataのCARである(文字列であること)。サブカテゴリーfile-errorは特別に処理される。

data内のオブジェクトの数と意味はerror-symbolに依存する。たとえばwrong-type-argumentエラーではリスト内に2つのオブジェクト — 期待する型を記述する述語とその型への適合に失敗したオブジェクト — であること。

エラーを処理する任意のエラーハンドラーにたいしてerror-symbolとdataの両方を利用できる。condition-caseはローカル変数を(error-symbol . data)というフォームでバインドする(エラーを処理するコードの記述を参照)。

関数signalは決してリターンしない。

(signal 'wrong-number-of-arguments '(x y))
     error→ Wrong number of arguments: x, y

(signal 'no-such-error '("My unknown error condition"))
     error→ peculiar error: "My unknown error condition"

Function: user-error format-string &rest args: この関数は、errorとまったく同じように振る舞うが、errorではなくエラーシンボルuser-errorを使用する。名前が示唆するように、このエラーはコード自身のエラーではなく、ユーザー側のエラーの報告を意図している。たとえばInfoの閲覧履歴の開始を超えて履歴を遡るためにコマンドInfo-history-back (l)を使用した場合、Emacsはuser-errorをシグナルする。このようなエラーでは、たとえdebug-on-errorが非nilであっても、デバッガーへのエントリーは発生しない。エラーによるデバッガへのエンターを参照のこと。

Common Lispに関する注意: Emacs LispにはCommon Lispのような継続可能なエラーのような概念は存在しない。

11.6.3.2 Emacsがエラーを処理する方法

エラーがシグナルされたとき、signalはそのエラーにたいするアクティブなハンドラー(handler)を検索します。ハンドラーとは、Lispプログラムの一部でエラーが発生したときに実行するよう意図されたLisp式のシーケンスです。そのエラーが適切なハンドラーをもっていればそのハンドラーが実行され、そのハンドラーの後から実行が再開されます。ハンドラーはそのハンドラーが設定されたcondition-caseの環境内で実行されます。condition-case内のすべての関数呼び出しはすでに終了しているので、ハンドラーがそれらにリターンすることはありません。

そのエラーにたいする適切なハンドラーが存在しなければ、カレントコマンドを終了してエディターのコマンドループに制御をリターンします(コマンドループにはすべての種類のエラーにたいする暗黙のハンドラーがある)。コマンドループのハンドラーは、エラーメッセージをプリントするためにエラーシンボルと、それに関連付けられたデータを使用します。変数command-error-functionを使用して、これが行なわれる方法を制御できます:

Variable: command-error-function: この変数が非nilなら、それはEmacsのコマンドループに制御をリターンしたエラーの処理に使用する関数を指定する。この関数は3つの引数を受け取る。1つ目のdataは、condition-caseが自身の変数にバインドするのと同じフォーム。2つ目のcontextはエラーが発生した状況を記述する文字列か、(大抵は)nil。3つ目のcallerはエラーをシグナルしたプリミティブ関数を呼び出したLisp関数。

明示的なハンドラーがないエラーは、Lispデバッガーを呼び出すかもしれません。変数debug-on-error (エラーによるデバッガへのエンターを参照)が非nilならデバッガーが有効です。エラーハンドラーと異なり、デバッガーはそのエラーの環境内で実行されるので、エラー時の変数の値を正確に調べることができます。

11.6.3.3 エラーを処理するコードの記述

エラーをシグナルすることによる通常の効果は、実行されていたコマンドを終了してEmacsエディターのコマンドループに即座にリターンすることです。スペシャルフォームcondition-caseを使用してエラーハンドラーを設定することにより、プログラム内の一部で発生するエラーのをトラップを調整することができます。以下は単純な例です:

(condition-case nil
    (delete-file filename)
  (error nil))

これはfilenameという名前のファイルを削除して、任意のエラーをcatch、エラーが発生した場合はnilをリターンします(このような単純なケースではマクロignore-errorsを使用することもできる。以下を参照のこと)。

condition-case構文は、insert-file-contents呼び出しによるファイルオープンの失敗のような、予想できるエラーをトラップするために多用されます。condition-case構文はユーザーから読み取った式を評価するプログラムのような、完全には予測できないエラーのトラップにも使用されます。

condition-caseの2番目の引数は保護されたフォーム(protected form)と呼ばれます(上記の例では保護されたフォームはdelete-fileの呼び出し)。このフォームの実行が開始されるとエラーハンドラーが効果をもち、このフォームがリターンすると不活性になります。その間のすべてにおいてエラーハンドラーは効果をもちます。特にこのフォームで呼び出された関数とそのサブルーチン等を実行する間、エラーハンドラーは効果をもちます。厳密にいうと保護されたフォーム自身ではなく、保護されたフォームから呼び出されたLispプリミティブ関数(signalとerrorを含む)だけがシグナルされるというのは、よいことと言えます。

保護されたフォームの後の引数はハンドラーです。各ハンドラーはそれぞれ、どのエラーを処理するかを指定する1つ以上のコンディション名(シンボル)をリストします。エラーがシグナルされたとき、エラーシンボルはコンディション名のリストも定義します。エラーが共通のコンディション名をもつ場合、そのハンドラーがそのエラーに適用されます。上記の例では1つのハンドラーがあり、それはすべてのエラーをカバーするコンディション名errorを指定しています。

適切なハンドラーの検索は、もっとも最近に設定されたハンドラーから始まり、設定されたすべてのハンドラーをチェックします。したがってネストされたcondition-caseフォームに同じエラー処理がある場合には、内側のハンドラーがそれを処理します。

何らかのcondition-caseによりエラーが処理されると、debug-on-errorでエラーによりデバッガーが呼び出されるようにしていても、通常はデバッガーの実行が抑制されます。

condition-caseで補足されるようなエラーをデバッグできるようにしたいなら、変数debug-on-signalに非nil値をセットします。以下のようにコンディション内にdebugを記述することにより、最初にデバッガーを実行するような特定のハンドラーを指定することもできます:

(condition-case nil
    (delete-file filename)
  ((debug error) nil))

ここでのdebugの効果は、デバッガー呼び出しを抑制するcondition-caseを防ぐことだけです。debug-on-errorとその他のフィルタリングメカニズムがデバッガーを呼び出すように指定されているときだけ、エラーによりデバッガーが呼び出されます。エラーによるデバッガへのエンターを参照してください。

Macro: condition-case-unless-debug var protected-form handlers…: マクロcondition-case-unless-debugは、そのようなフォームのデバッギングを処理する、別の方法を提供する。このマクロは変数debug-on-errorがnil、つまり任意のエラーを処理しないようなケース以外は、condition-caseとまったく同様に振る舞う。

特定のハンドラーがそのエラーを処理するとEmacsが判断すると、Emacsは制御をそのハンドラーにreturnします。これを行うために、Emacsはそのとき脱出しつつあるバインディング構成により作成されたすべての変数のバインドを解き、そのとき脱出しつつあるすべてのunwind-protectフォームを実行します。制御がそのハンドラーに達すると、そのハンドラーのbodyが通常どおり実行されます。

そのハンドラーのbodyを実行した後、condition-caseフォームから実行がreturnされます。保護されたフォームは、そのハンドラーの実行の前に完全にexitしているので、そのハンドラーはそのエラーの位置から実行を再開することはできず、その保護されたフォーム内で作られた変数のバインディングを調べることもできません。ハンドラーが行なえることは、クリーンアップと、処理を進行させることだけです。

エラーのシグナルとハンドルにはthrowとcatch (明示的な非ローカル脱出: catchとthrowを参照)に類似する点がいくつかありますが、これらは完全に別の機能です。エラーはcatchでキャッチできず、throwをエラーハンドラーで処理することはできません(しかし対応するcatchが存在しないときにthrowを使用することによりシグナルされるエラーは処理できる)。

Special Form: condition-case var protected-form handlers…

このスペシャルフォームはprotected-formの実行を囲い込むエラーハンドラーhandlersを確立する。エラーなしでprotected-formが実行されると、リターンされる値はcondition-caseフォームの値になる。この場合、condition-caseは効果をもたない。protected-formの間にエラーが発生すると、condition-caseフォームは違いを生じる。

handlersはそれぞれ、(conditions body…)というフォームのリストである。ここでconditionsはハンドルされるエラーコンディション名、またはそのハンドラーの前にデバッガーを実行するためのコンディション名(debugを含む)。bodyはこのハンドラーがエラーを処理するときに実行される1つ以上のLisp式。

(error nil)

(arith-error (message "Division by zero"))

((arith-error file-error)
 (message
  "Either division by zero or failure to open a file"))

発生するエラーはそれぞれ、それが何の種類のエラーかを記述するエラーシンボル(error symbol)をもち、これはコンディション名のリストも記述する(エラーシンボルとエラー条件を参照)。Emacsは1つ以上のコンディション名を指定するハンドラーにたいして、すべてのアクティブなcondition-caseフォームを検索する。condition-caseの最内のマッチがそのエラーを処理する。condition-case内では、最初に適合したハンドラーがそのエラーを処理する。

ハンドラーのbodyを実行した後、condition-caseは通常どおりリターンして、ハンドラーのbodyの最後の値をハンドラー全体の値として使用する。

引数varは変数である。protected-formを実行するとき、condition-caseはこの変数をバインドせず、エラーを処理するときだけバインドする。その場合には、varをエラー記述(error description)にバインドする。これはエラーの詳細を与えるリストである。このエラー記述は(error-symbol . data)というフォームをもつ。ハンドラーは何を行なうか決定するために、このリストを参照することができる。たとえばファイルオープンの失敗にたいするエラーなら、ファイル名がdata(エラー記述の3番目の要素)の2番目の要素になる。

varがnilなら、それはバインドされた変数がないことを意味する。この場合、エラーシンボルおよび関連するデータは、そのハンドラーでは利用できない。

より外側のレベルのハンドラーにcatchさせるために、condition-caseによりcatchされたシグナルを再度throwする必要がある場合もある。以下はこれを行なう方法である:

  (signal (car err) (cdr err))

ここでerrはエラー記述変数(error description variable)で、condition-caseの1番目の引数は、再throwしたいエラーコンディション。Definition of signalを参照のこと。

Function: error-message-string error-descriptor: この関数は与えられたエラー記述子(error descriptor)にたいするエラーメッセージ文字列をリターンする。これはそのエラーにたいする通常のエラーメッセージをプリントすることにより、エラーを処理したい場合に有用。Definition of signalを参照のこと。

以下は0除算の結果によるエラーを処理するために、condition-caseを使用する例です。このハンドラーは、(beepなしで)エラーメッセージを表示して、非常に大きい数をリターンします。

(defun safe-divide (dividend divisor)
  (condition-case err
      ;; 保護されたフォーム
      (/ dividend divisor)

    ;; ハンドラー
    (arith-error                        ; コンディション
     ;; このエラーにたいする、通常のメッセージを表示する
     (message "%s" (error-message-string err))
     1000000)))
⇒ safe-divide

(safe-divide 5 0)
     -| Arithmetic error: (arith-error)
⇒ 1000000

このハンドラーはコンディション名arith-errorを指定するので、division-by-zero(0除算)エラーだけを処理します。他の種類のエラーは(このcondition-caseによっては)、処理されません。したがって:

(safe-divide nil 3)
     error→ Wrong type argument: number-or-marker-p, nil

以下はerrorによるエラーを含む、すべての種類のエラーをcatchするcondition-caseです:

(setq baz 34)
     ⇒ 34

(condition-case err
    (if (eq baz 35)
        t
      ;; 関数errorの呼び出し
      (error "Rats!  The variable %s was %s, not 35" 'baz baz))
  ;; フォームではないハンドラー
  (error (princ (format "The error was: %s" err))
         2))
-| The error was: (error "Rats!  The variable baz was 34, not 35")
⇒ 2

Macro: ignore-errors body…

この構文は、それの実行中に発生する任意のエラーを無視してbodyを実行する。その実行中にエラーがなければ、ignore-errorsはbody内の最後のフォームの値を、それ以外はnilをリターンする。

以下はこのセクションの最初の例をignore-errorsを使用して記述する例である:

  (ignore-errors
   (delete-file filename))

Macro: with-demoted-errors format body…: このマクロはいわばignore-errorsの穏やかなバージョンである。これはエラーを完全に抑止するのではなく、エラーをメッセージに変換する。これはメッセージのフォーマットに、文字列formatを使用する。formatは"Error: %S"のように、単一の‘%’シーケンスを含むこと。エラーをシグナルするとは予測されないが、もし発生した場合は堅牢であるべきようなコードの周囲にwith-demoted-errorsを使用する。このマクロはcondition-caseではなく、condition-case-unless-debugを使用することに注意。

11.6.3.4 エラーシンボルとエラー条件

エラーをシグナルするとき、想定するエラーの種類を指定するためにエラーシンボル(error symbol)を指定します。エラーはそれぞれ、それをカテゴリー分けするために単一のエラーシンボルをもちます。これはEmacs Lisp言語で定義されるエラーを分類する、もっともよい方法です。

これらの狭義の分類はエラー条件(error conditions)と呼ばれる、より広義のクラス階層にグループ化され、それらはコンディション名(condition names)により識別されます。そのようなもっとも狭義なクラスは、エラーシンボル自体に属します。つまり各エラーシンボルは、コンディション名でもあるのです。すべての種類のエラー(quitを除く)を引き受けるコンディション名errorに至る、より広義のクラスにたいするコンディション名も存在します。したがって各エラーは1つ以上のコンディション名をもちます。つまりerror、errorとは区別されるエラーシンボル、もしかしたらその中間に分類されるものかもしれません。

Function: define-error name message &optional parent: シンボルをエラーシンボルとするために、シンボルは親コンディションを受け取るdefine-errorで定義されなければならない。この親はその種のエラーが属するコンディションを定義する。親の推移的な集合は、常にそのエラーシンボルとシンボルerrorを含む。quitはエラーと判断されないので、quitの親の集合は単なる(quit)である。

親のコンディションに加えてエラーシンボルはメッセージ(message)をもち、これは処理されないエラーがシグナルされたときプリントされる文字列です。そのメッセージが有効でなければ、エラーメッセージ‘peculiar error’が使用されます。Definition of signalを参照してください。

内部的には親の集合はエラーシンボルのerror-conditionsプロパティーに格納され、メッセージはエラーシンボルのerror-messageプロパティーに格納されます。

以下は新しいエラーシンボルnew-errorを定義する例です:

(define-error 'new-error "A new error" 'my-own-errors)

このエラーは複数のコンディション名 — もっとも狭義の分類new-error、より広義の分類を想定するmy-own-errors、およびmy-own-errorsのコンディションすべてを含むerrorであり、これはすべての中でもっとも広義なものです。

エラー文字列は大文字で開始されるべきですが、ピリオドで終了すべきではありません。これはEmacsの他の部分との整合性のためです。

もちろんEmacs自身がnew-errorをシグナルすることはありません。あなたのコード内で明示的にsignal (Definition of signalを参照)を呼び出すことにより、これを行なうことができます。

(signal 'new-error '(x y))
     error→ A new error: x, y

このエラーは、エラーの任意のコンディション名により処理することができます。以下の例はnew-errorとクラスmy-own-errors内の他の任意のエラーを処理します:

(condition-case foo
    (bar nil t)
  (my-own-errors nil))

エラーが分類される有効な方法はコンディション名による方法で、その名前はハンドラーのエラーのマッチに使用されます。エラーシンボルは意図されたエラーメッセージと、コンディション名のリストを指定する便利な方法であるという役割をもつだけです。1つのエラーシンボルではなく、コンディション名のリストをsignalに与えるのは面倒でしょう。

対照的にコンディション名を伴わずにエラーシンボルだけを使用すると、それはcondition-caseの効果を著しく減少させるでしょう。コンディション名はエラーハンドラーを記述するとき、一般性のさまざまなレベルにおいて、エラーをカテゴリー分けすることを可能にします。エラーシンボルを単独で使用することは、もっとも狭義なレベルの分類を除くすべてを捨ててしまうことです。

主要なエラーシンボルとそれらのコンディションについては、標準的なエラーを参照してください。

11.6.4 非ローカル脱出のクリーンアップ

unwind-protect構文は、データ構造を一時的に不整合な状態に置くときに重要です。これはエラーやthrouのイベントにより、再びデータを整合された状態にすることができます(バッファー内容の変更だけに使用される他のクリーンアップ構成はアトミックな変更グループである。グループのアトミックな変更を参照)。

Special Form: unwind-protect body-form cleanup-forms…

unwind-protectは制御がbody-formを離れる場合に、cleanup-formsが評価されるという保証の下において、何が起こったかに関わらずbody-formを実行する。body-formは通常どおり完了するかもしれず、unwind-protectの外側でthrowの実行やエラーが発生するかもしれないが、cleanup-formsは評価される。

body-formが正常に終了したら、unwind-protectはcleanup-formsを評価した後に、body-formの値をリターンする。body-formが終了しなかったら、unwind-protectは通常の意味におけるような値はリターンしない。

unwind-protectで保護されるのはbody-formだけである。cleanup-forms自体の任意のフォームが、(throwまたはエラーにより)非ローカルにexitすると、unwind-protectは残りのフォームが評価されることを保証しない。cleanup-formsの中の1つが失敗することが問題となるようなら、そのフォームの周囲に他のunwind-protectを配置して保護すること。

現在アクティブなunwind-protectフォーム数とローカルの変数バインディング数の和は、max-specpdl-size (Local Variablesを参照)により制限される。

たとえば以下は一時的な使用のために不可視のバッファーを作成して、終了する前に確実にそのバッファーをkillする例です:

(let ((buffer (get-buffer-create " *temp*")))
  (with-current-buffer buffer
    (unwind-protect
        body-form
      (kill-buffer buffer))))

(kill-buffer (current-buffer))のように記述して、変数bufferを使用せずに同様のことを行えると思うかもしれません。しかし上の例は、別のバッファーにスイッチしたときにbody-formでエラーが発生した場合、より安全なのです(一時的なバッファーをkillするとき、そのバッファーがカレントとなることを確実にするために、かわりにbody-formの周囲にsave-current-bufferを記述することもできる)。

Emacsには上のコードとおおよそ等しいコードに展開される、with-temp-bufferという標準マクロが含まれます(Current Bufferを参照)。このマニュアル中で定義されるいくつかのマクロは、この方法でunwind-protectを使用します。

以下はFTPパッケージ由来の実例です。これはリモートマシンへの接続の確立を試みるために、プロセス(プロセスを参照)を作成しています。関数ftp-loginは関数のライター(writer)が予想できないことによる多くの問題から非常に影響を受けるので、失敗イベントでプロセスの削除を保証するフォームで保護されています。そうしないとEmacsは無用なサブプロセスで一杯になってしまうでしょう。

(let ((win nil))
  (unwind-protect
      (progn
        (setq process (ftp-setup-buffer host file))
        (if (setq win (ftp-login process host user password))
            (message "Logged in")
          (error "Ftp login failed")))
    (or win (and process (delete-process process)))))

この例には小さなバグがあります。ユーザーがquitするためにC-gとタイプすると、関数ftp-setup-bufferのリターン後に即座にquitが発生しますが、それは変数processがセットされる前なので、そのプロセスはkillされないでしょう。このバグを簡単に訂正する方法はありませんが、少なくともこれは非常に稀なことだと言えます。

12 変数

変数(variable)とはプログラム内で値を表すために使用される名前です。Lispでは変数はそれぞれLispシンボルとして表されます(シンボルを参照)。変数名は単にそのシンボルの名前であり、変数の値はそのシンボルの値セル(value cell)に格納されます⁶。シンボルの構成要素を参照してください。Emacs Lispではシンボルを変数として使用することは、同じシンボルを関数名として使用することと関係ありません。

このマニュアルで前述したとおり、Lispプログラムはまず第1にLispオブジェクトとして表され、副次的にテキストとして表現されます。Lispプログラムのテキスト的な形式は、そのプログラムを構成するLispオブジェクトの入力構文により与えられます。したがってLispプログラム内の変数のテキスト的な形式は、その変数を表すシンボルの入力構文を使用して記述されます。

12.1 グローバル変数		どの場所でも永続的に存在する変数の値。
12.2 変更不可な変数		Variables that never change.
12.3 ローカル変数		一時的にのみ存在する存在する変数の値。
12.4 When a Variable is Void		値を持たないシンボル。
12.5 グローバル変数の定義		シンボルが変数として使用されていることを宣言する定義。
12.6 堅牢な変数定義のためのヒント		変数を定義するときに考慮すべき事項。
12.7 変数の値へのアクセス		実行時に判明する名前をもつ変数の値を確認する。
12.8 変数の値のセット		変数に新しい値を格納する。
12.9 Running a function when a variable is changed.
12.10 変数のバインディングのスコーピングルール		Lispがローカル値とグローバル値を選択する方法。
12.11 バッファーローカル変数		1つのバッファーないだけで効果をもつ変数の値。
12.12 ファイルローカル変数		ファイル内にリストされたローカル変数の処理。
12.13 ディレクトリーローカル変数		ディレクトリー内のすべてのファイルで共通のローカル変数。
12.14 Connection Local Variables		Local variables common for remote connections.
12.15 変数のエイリアス		他の変数のエイリアスとなる変数。
12.16 値を制限された変数		任意のLispオブジェクトを値とすることができない、定数ではない変数。
12.17 ジェネリック変数		変数の概念の拡張。

12.1 グローバル変数

変数を使用するための一番シンプルな方法は、グローバル(globally)を使用する方法です。これはある時点でその変数はただ1つの値をもち、その値が(少なくともその時点では)Lispシステム全体で効果をもつことを意味します。あらたな値を指定するまでその値が効果をもちます。新しい値で古い値を置き換えるとき、古い値を追跡する情報は変数内に残りません。

シンボルの値はsetqで指定します。たとえば、

(setq x '(a b))

これは変数xに値(a b)を与えます。setqはスペシャルフォームであることに注意してください。これは1番目の引数(変数の名前)は評価しませんが、2番目の引数(新しい値)は評価します。

変数が一度値をもつと、そのシンボル自身を式として使用することによって参照することができます。したがって、

x ⇒ (a b)

これは上記のsetqフォームが実行された場合です。

同じ変数を再びセットすると、古い値は新しい値で置き換えられます:

x
     ⇒ (a b)

(setq x 4)
     ⇒ 4

x
     ⇒ 4

12.2 変更不可な変数

Emacs Lispでは特定のシンボルは、通常は自分自身に評価されます。これらのシンボルにはnilとt、同様に名前が‘:’で始まる任意のシンボル(これらはキーワードと呼ばれる)が含まれます。これらのシンボルはリバインドや、値の変更はできません。nilやtへのセットやリバインドは、setting-constantエラーをシグナルします。これはキーワード(名前が‘:’で始まるシンボル)についても当てはまります。ただしキーワードが標準のobarrayにinternされていれば、そのようなシンボルを自分自身にセットしてもエラーになりません。

nil ≡ 'nil
     ⇒ nil

(setq nil 500)
error→ Attempt to set constant symbol: nil

Function: keywordp object: この関数はobjectが‘:’で始まる名前のシンボルであり、標準のobarrayにinternされていればt、それ以外はnilをリターンする。

これらの定数はスペシャルフォームdefconst(グローバル変数の定義を参照)を使用して定義された定数(constant)とは根本的に異なります。defconstフォームは、人間の読み手に値の変更を意図しない変数であることを知らせる役目は果たしますが、実際にそれを変更してもEmacsはエラーを起こしません。

A small number of additional symbols are made read-only for various practical reasons. These include enable-multibyte-characters, most-positive-fixnum, most-negative-fixnum, and a few others. Any attempt to set or bind these also signals a setting-constant error.

12.3 ローカル変数

グローバル変数は新しい値で明示的に置き換えるまで値が持続します。変数にローカル値(local value) — Lispプログラム内の特定の部分で効果をもつ — を与えると便利なときがあります。変数がローカル値をもつとき、わたしたちは変数がその値にローカルにバインド(locally bound)されていると言い、その変数をローカル変数(local variable)と呼びます。

For example, when a function is called, its argument variables receive local values, which are the actual arguments supplied to the function call; these local bindings take effect within the body of the function. To take another example, the let special form explicitly establishes local bindings for specific variables, which take effect only within the body of the let form.

これにたいしてグローバルなバインディング(global binding)とは、(概念的には)グローバルな値が保持される場所です。

ローカルバインディングを確立すると、その変数の以前の値は他の場所に保存されます(または失われる)。わたしたちはこれを、以前の値がシャドー(shadowed)されたと言います。シャドーはグローバル変数とローカル変数の両方で発生し得ます。ローカルバインディングが効果を持つときには、ローカル変数にsetqを使用することにより、指定した値をローカルバインディングに格納します。ローカルバインディングが効果を持たなくなったとき、以前にシャドーされた値が復元されます(または失われる)。

変数は同時に複数のローカルバインディングを持つことができます(たとえばその変数をバインドするネストされたlet)。カレントバインディング(current binding)とは、実際に効果を持つローカルバインディングのことです。カレントバインディングは、その変数の評価によりリターンされる値を決定し、setqにより影響を受けるバインディングです。

ほとんどの用途において、最内(innermost)のローカルバインディングとローカルバインディングをもたないグローバルバインディングを、カレントバインディングと考えることができます。より正確に言うと、スコープルール(scoping rule)と呼ばれるルールは、プログラム内でローカルバインディングが効果を持つ任意の与えられた場所を決定します。Emacs Lispのスコープルールはダイナミックスコープ(dynamic scoping)と呼ばれ、これは単に実行中のプログラム内の与えられた位置でのカレントバインディングを示しており、その変数がまだ存在すれば、その変数にたいしてもっとも最近作成されたバインディングです。ダイナミックスコープについての詳細、およびその代替であるレキシカルスコープ(lexical scoping)と呼ばれるスコープルールについては、変数のバインディングのスコーピングルールを参照してください。

スペシャルフォームletとlet*は、ローカルバインディングを作成するために存在します:

Special Form: let (bindings…) forms…

This special form sets up local bindings for a certain set of variables, as specified by bindings, and then evaluates all of the forms in textual order. Its return value is the value of the last form in forms. The local bindings set up by let will be in effect only within the body of forms.

bindingsの各バインディングは2つの形式のいずれかである。(i) シンボルなら、そのシンボルはnilにローカルにバインドされる。(ii) フォーム(symbol value-form)のリストなら、symbolはvalue-formを評価した結果へローカルにバインドされる。value-formが省略されたらnilが使用される。

bindings内のすべてのvalue-formは、シンボルがそれらにバインドされる前に、記述された順番に評価される。以下の例ではzはyの新しい値(つまり1)にではなく、古い値(つまり2)にバインドされる。

(setq y 2)
     ⇒ 2

(let ((y 1)
      (z y))
  (list y z))
     ⇒ (1 2)

On the other hand, the order of bindings is unspecified: in the following example, either 1 or 2 might be printed.

(let ((x 1)
      (x 2))
  (print x))

Therefore, avoid binding a variable more than once in a single let form.

Special Form: let* (bindings…) forms…

このスペシャルフォームはletと似ているが、次の変数値にたいするローカル値を計算する前に、ローカル値を計算してそれを変数にバインドする。したがてbindings内の式は、このlet*フォーム内の前のシンボルのバインドを参照できる。以下の例を上記letの例と比較されたい。

(setq y 2)
     ⇒ 2

(let* ((y 1)
       (z y))    ; yの値に今計算されたばかりの値を使用する
  (list y z))
     ⇒ (1 1)

以下はローカルバインディングを作成する他の機能のリストです:

関数呼び出し(関数を参照)。
マクロ呼び出し(マクロを参照)。
condition-case (エラーを参照)。

変数はバッファーローカルなバインディングを持つこともできます(バッファーローカル変数を参照)。数は多くありませんが、端末ローカル(terminal-local)なバインディングをもつ変数もあります(複数の端末を参照)。この種のバインディングは、通常のローカルバインディングのように機能することもありますが、これらはEmacs内のどこにいるかに依存してローカルになります。

User Option: max-specpdl-size

この変数はローカルな変数バインディングと、unwind-protectにゆるクリーンアップ(Cleaning Up from Nonlocal Exitsを参照)の総数にたいする制限を定義し、この変数を越えるとEmacsは(データ"Variable binding depth exceeds max-specpdl-size"とともに)エラーをシグナルする。

このリミットは、もし超過したときにエラーが関連付けられていれば、誤って定義された関数による無限再起を避けるための1つの手段になる。ネストの深さにたいする他の制限としては、max-lisp-eval-depthがある。Evalを参照のこと。

デフォルト値は1300。Lispデバッガーのエントリーしたとき、もし残りが少なければ、デバッガーを実行するための空きを作るために値が増加される。

12.4 When a Variable is Void

シンボルの値セル(シンボルの構成要素を参照)に値が割り当てられていない場合、その変数はvoid(空)であると言います。

Emacs Lispのデフォルトであるダイナミックスコープルール(変数のバインディングのスコーピングルールを参照)の下では、値セルはその変数のカレント値(ローカルまたはグローバル)を保持します。値が割り当てられていない値セルは、値セルにnilをもつのとは異なることに注意してください。シンボルnilはLispオブジェクトであり、他のオブジェクトと同様に変数の値となることができます。nilは値なのです。変数がvoidの場合にその変数の評価を試みると、値をリターンするかわりに、void-variableエラーがシグナルされます。

オプションであるレキシカルスコープルール(lexical scoping rule)の下では、値セル保持できるのはその変数のグローバル値 — 任意のレキシカルバインディング構造の外側の値だけです。変数がレキシカルにバインドされている場合、ローカル値はそのレキシカル環境により決定されます。したがってこれらのシンボルの値セルに値が割り当てられていなくても、変数はローカル値を持つことができます。

Function: makunbound symbol

この関数はsymbolの値セルを空にして、その変数をvoidにする。この関数はsymbolをリターンする。

symbolがダイナミックなローカルバインディングをもつなら、makunboundはカレントのバインディングをvoidにして、そのローカルバインディングが効果を持つ限りvoidにする。その後で以前にシャドーされたローカル値(またはグローバル値)が再び有効になって、再び有効になった値がvoidでなければ、その変数はvoidではなくなる。

いくつか例を示す(ダイナミックバインディングが有効だとする):

(setq x 1)               ; グローバルバインディングに値をセットする
     ⇒ 1
(let ((x 2))             ; それをローカルにバインドする
  (makunbound 'x)        ; ローカルバインディングをvoidにする
  x)
error→ Symbol's value as variable is void: x

x                        ; グローバルバインディングは変更されない
     ⇒ 1

(let ((x 2))             ; ローカルにバインドする
  (let ((x 3))           ; もう一度
    (makunbound 'x)      ; 最内のローカルバインディングをvoidにする
    x))                  ; それを参照すると、void
error→ Symbol's value as variable is void: x

(let ((x 2))
  (let ((x 3))
    (makunbound 'x))     ; 内側のバインディングをvoidにしてから取り除く
  x)                     ; 外側のletバインディングが有効になる
     ⇒ 2

Function: boundp variable

この関数はvariable(シンボル)がvoidでなければt、voidならnilをリターンする。

いくつか例を示す(ダイナミックバインディングが有効だとする):

(boundp 'abracadabra)          ; 最初はvoid
     ⇒ nil

(let ((abracadabra 5))         ; ローカルにバインドする
  (boundp 'abracadabra))
     ⇒ t

(boundp 'abracadabra)          ; グローバルではまだvoid
     ⇒ nil

(setq abracadabra 5)           ; グローバルで非voidにする
     ⇒ 5

(boundp 'abracadabra)
     ⇒ t

12.5 グローバル変数の定義

変数定義(variable definition)とは、そのシンボルをグローバル変数として使用する意図を表明する構文です。これには以下で説明するスペシャルフォームdefvarやdefconstが使用されます。

変数宣言は3つの目的をもちます。1番目はコードを読む人にたいして、そのシンボルが特定の方法(変数として)使用されることを意図したものだと知らせることです。2番目はLispシステムにたいしてオプションで初期値とドキュメント文字列を与えて、これを知らせることです。3番目はetagsのようなプログラミングツールにたいして、その変数が定義されている場所を見つけられるように情報を提供することです。

defconstとdefvarの主な違いは、人間の読み手に値が変更されるかどうかを知らせることにあります。Emacs Lispは実際に、defconstで定義された変数の値の変更を妨げません。この2つのフォームの特筆すべき違いは、defconstは無条件で変数を初期化して、defvarは変数が元々voidのときだけ初期化することです。

カスタマイズ可能な変数を定義する場合は、defcustomを使用するべきです(これはサブルーチンとしてdefvarを呼び出す)。カスタマイズ変数の定義を参照してください。

Special Form: defvar symbol [value [doc-string]]

このスペシャルフォームは変数としてsymbolを定義する。symbolが評価されないことに注意。シンボルはdefvarフォーム内に明示的に表記して定義される必要がある。この変数は特別だとマークされて、これは常に変数がダイナミックにバインドされることを意味する(変数のバインディングのスコーピングルールを参照)。

valueが指定されていてsymbolがvoid(たとえばこのシンボルがダイナミックにバインドされた値を持たないとき。When a Variable is Voidを参照)ならvalueが評価されて、その結果がsymbolにセットされる。しかしsymbolがvoidでなければ、valueは評価されずsymbolの値は変更されない。valueが省略された場合は、いかなる場合もsymbolの値は変更されない。

Note that specifying a value, even nil, marks the variable as special permanently. Whereas if value is omitted then the variable is only marked special locally (i.e. within the current lexical scope, or file if at the top-level). This can be useful for suppressing byte compilation warnings, see コンパイラーのエラー.

symbolがカレントバッファー内でバッファーローカルなバインディングをもつ場合、defvarはデフォルト値に作用する。デフォルト値はバッファーローカルなバインディングではなく、バッファーにたいして独立である。デフォルト値がvoidのときはデフォルト値をセットする。バッファーローカル変数を参照のこと。

すでにsymbolがレキシカルにバインドされている場合(たとえばレキシカルバインドが有効な状態でletフォーム内にdefvarがあるような場合)、defvarはダイナミックな値をセットする。バインディング構文を抜けるまで、レキシカルバインディングは効果をもつ。変数のバインディングのスコーピングルールを参照のこと。

Emacs LispモードでC-M-x (eval-defun)でトップレベルのdefvarを評価するとき、eval-defunの特別な機能はその値がvoidであるかテストすることなく、その変数を無条件にセットする。

引数doc-stringが与えられたら、それは変数にたいするドキュメント文字列を指定する(そのシンボルのvariable-documentationプロパティーに格納される)。ドキュメントを参照のこと。

以下にいくつか例を示す。これはfooを定義するが初期化は行わない:

(defvar foo)
     ⇒ foo

以下の例はbarの値を23に初期化してドキュメント文字列を与える:

(defvar bar 23
  "The normal weight of a bar.")
     ⇒ bar

defvarフォームはsymbolをリターンするが、これは通常は値が問題にならないファイル内のトップレベルで使用される。

For a more elaborate example of using defvar without a value, see Local defvar example.

Special Form: defconst symbol value [doc-string]

このスペシャルフォームはある値でsymbolを定義して、それを初期化する。これはコードを読む人に、symbolがここで設定される標準的なグローバル値をもち、ユーザーや他のプログラムがそれを変更すべきではないことを知らせる。symbolが評価されないことに注意。定義されるシンボルはdefconst内に明示的に記されなければならない。

defvarと同様、defconstは変数を特別 — この変数が常にダイナミックにバインドされているという意味 — であるとマークする(変数のバインディングのスコーピングルールを参照)。加えてこれはその変数を危険であるとマークする(ファイルローカル変数を参照)。

defconstは常にvalueを評価して、その結果をsymbolの値にセットする。カレントバッファー内でsymbolがバッファーローカルなバインディングをもつなら、defconstはデフォルト値ではなくバッファーローカルな値をセットする(しかしdefconstで定義されたシンボルにたいしてバッファーローカルなバインディングを作らないこと)。

defconstの使い方の例は、Emacsのfloat-pi — (たとえインディアナ州議会が何を試みようと)何者かにより変更されるべきではない数学定数piにたいする定義である。しかし2番目のdefconstの例のように、これは単にアドバイス的なものである。

(defconst float-pi 3.141592653589793 "The value of Pi.")
     ⇒ float-pi

(setq float-pi 3)
     ⇒ float-pi

float-pi
     ⇒ 3

警告: 変数がローカルバインディングをもつとき(letにより作成された、または関数の引数の場合)に、スペシャルフォームdefconstまたはdefvarを使用すると、これらのフォームはグローバルバインディングではなく、ローカルバインディングをセットします。これは通常は、あなたが望むことではないはずです。これを防ぐには、これらのスペシャルフォームをファイル内のトップレベルで使用します。この場所は通常、何のローカルバインディングも効果をもたないので、その変数にたいするローカルバインディングが作成される前にファイルがロードされることが確実だからです。

12.6 堅牢な変数定義のためのヒント

値が関数(または関数のリスト)であるような変数を定義するときには、変数の名前の最後に‘-function’(または‘-functions’)を使用します。

他にも変数名に関する慣習があります。以下はその完全なリストです:

‘…-hook’: 変数はノーマルフック(フックを参照)。
‘…-function’: 値は関数。
‘…-functions’: 値は関数のリスト。
‘…-form’: 値はフォーム(式)。
‘…-forms’: 値はフォーム(式)のリスト。
‘…-predicate’: 値は述語(predicate) — 1つの引数をとる関数 — であり成功なら非nil、失敗ならnilをリターンする。
‘…-flag’: nilか否かだけが意味をもつような値。結局そのような変数は、やがては多くの値をもつことが多いので、この慣習を強く推奨はしない。
‘…-program’: 値はプログラム名。
‘…-command’: 値は完全なシェルコマンド。
‘…-switches’: 値はコマンドにたいして指定するオプション。
‘prefix--…’: The variable is intended for internal use and is defined in the file prefix.el. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)
‘…-internal’: The variable is intended for internal use and is defined in C code. (Emacs code contributed before 2018 may follow other conventions, which are being phased out.)

変数を定義するときは、その変数を安全(safe)とマークすべきか、それとも危険(risky)とマークすべきかを常に考慮してください。ファイルローカル変数を参照してください。

複雑な値を保持する変数(バインディングをもつkeymapなど)の定義や初期化を行う場合は、以下のように値の計算をすべてdefvarの中に配置するのが最良です:

(defvar my-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-a" 'my-command)
    …
    map)
  docstring)

この方法にはいくつかの利点があります。1つ目はファールをロード中にユーザーが中断した場合、変数はまだ初期化されていないか、初期化されているかのどちらかであり、その中間ということはありません。まだ初期化されていなければ、ファイルをリロードすれば正しく初期化されます。2つ目は一度初期化された変数は、ファイルをリロードしても変更されないことです。コンテンツの一部を変更(たとえばキーのリバインド)するフックをユーザーが実行した場合などに、これは重要です。3つ目はC-M-xでdefvarを評価すると、そのマップは完全に再初期化されることです。

defvarフォーム内に多すぎるコードを配置することが不利な点が1つあります。ドキュメント文字列が変数の名前から離れた場所に配置されることです。これを避ける安全な方法は以下の方法です:

(defvar my-mode-map nil
  docstring)
(unless my-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\C-c\C-a" 'my-command)
    …
    (setq my-mode-map map)))

これは初期化をdefvarの内側に配置した場合とまったく同じ利点をもちますが、変数を再度初期化したい場合は、各フォームにたいして1回ずつ、C-M-xを2回タイプしなければならない点が異なります。

12.7 変数の値へのアクセス

変数を参照する通常の方法は、それに名前をつけるシンボルを記述する方法です。シンボルのフォームを参照してください。

実行時にのみ決定される変数を参照したいときがあるかもしれません。そのような場合、プログラム中のテキストで変数名を指定することはできません。そのような値を抽出するためにsymbol-valueを使うことができます。

Function: symbol-value symbol

この関数はsymbolの値セルに格納された値をリターンする。これはその変数の(ダイナミックな)カレント値が格納された場所である。その変数がローカルバインディングをもたなければ単にその変数のグローバル値になる。変数がvoidならvoid-variableはエラーをシグナルする。

その変数がレキシカルにバインドされていれば、symbol-valueが報告する値は、その変数のレキシカル値と同じである必要はない。レキシカル値はそのシンボルの値セルではなく、レキシカル環境により決定される。変数のバインディングのスコーピングルールを参照のこと。

(setq abracadabra 5)
     ⇒ 5

(setq foo 9)
     ⇒ 9

;; ここでシンボルabracadabra
;;   は値がテストされるシンボル
(let ((abracadabra 'foo))
  (symbol-value 'abracadabra))
     ⇒ foo

;; ここではabracadabraの値、
;;   つまりfooが値を
;;   テストされるシンボル
(let ((abracadabra 'foo))
  (symbol-value abracadabra))
     ⇒ 9

(symbol-value 'abracadabra)
     ⇒ 5

12.8 変数の値のセット

ある変数の値を変更する通常の方法は、スペシャルフォームsetqを使用する方法です。実行時に変数選択を計算する必要がある場合には関数setを使用します。

Special Form: setq [symbol form]…

このスペシャルフォームは、変数の値を変更するためのもっとも一般的な方法である。symbolにはそれぞれ、新しい値(対応するformが評価された結果)が与えられる。そのシンボルのカレントバインディングは変更される。

setqはsymbolを評価せずに、記述されたシンボルをセットする。この引数のことを自動的にクォートされた(automatically quoted)と呼ぶ。setqの‘q’は“quoted(クォートされた)”が由来。

setqフォームの値は最後のformの値となる。

(setq x (1+ 2))
     ⇒ 3

x                   ; ここでxはグローバル値をもつ
     ⇒ 3

(let ((x 5))
  (setq x 6)        ; xのローカルバインディングをセット
  x)
     ⇒ 6

x                   ; グローバル値は変更されない
     ⇒ 3

1番目のformが評価されてから1番目のsymbolがセット、次に2番目のformが評価されてからsymbolが評価されて、...となることに注意:

(setq x 10          ; ここで、xがセットされるのは
      y (1+ x))     ;   yの計算前であることに注目
     ⇒ 11

Function: set symbol value

この関数はsymbolの値セルにvalueを配置する。これはスペシャルフォームではなく関数なので、シンボルにセットするためにsymbolに記述された式は評価される。リターン値はvalue。

ダイナミックな変数バインドが有効(デフォルト)なら、setは自身の引数symbolを評価するが、setqは評価しないという点を除き、setはsetqと同じ効果をもつ。しかし変数がレキシカルバインドなら、setは変数のダイナミックな値に、setqは変数のカレント値(レキシカル値)に影響する。変数のバインディングのスコーピングルールを参照のこと。

(set one 1)
error→ Symbol's value as variable is void: one

(set 'one 1)
     ⇒ 1

(set 'two 'one)
     ⇒ one

(set two 2)         ; twoはシンボルoneに評価される
     ⇒ 2

one                 ; したがってoneがセットされる
     ⇒ 2
(let ((one 1))      ; oneのこのバインディングがセットされる
  (set 'one 3)      ;   のであってグローバル値はセットされない
  one)
     ⇒ 3

one
     ⇒ 2

symbolが実際のシンボルでなければwrong-type-argumentエラーがシグナルされる。

(set '(x y) 'z)
error→ Wrong type argument: symbolp, (x y)

12.9 Running a function when a variable is changed.

It is sometimes useful to take some action when a variable changes its value. The watchpoint facility provides the means to do so. Some possible uses for this feature include keeping display in sync with variable settings, and invoking the debugger to track down unexpected changes to variables (see section Entering the debugger when a variable is modified).

The following functions may be used to manipulate and query the watch functions for a variable.

Function: add-variable-watcher symbol watch-function

This function arranges for watch-function to be called whenever symbol is modified. Modifications through aliases (see section 変数のエイリアス) will have the same effect.

watch-function will be called with 4 arguments: (symbol newval operation where).

symbol is the variable being changed. newval is the value it will be changed to. operation is a symbol representing the kind of change, one of: ‘set’, ‘let’, ‘unlet’, ‘makunbound’, and ‘defvaralias’. where is a buffer if the buffer-local value of the variable is being changed, nil otherwise.

Function: remove-variable-watch symbol watch-function: This function removes watch-function from symbol’s list of watchers.

Function: get-variable-watchers symbol: This function returns the list of symbol’s active watcher functions.

12.9.1 Limitations

There are a couple of ways in which a variable could be modified (or at least appear to be modified) without triggering a watchpoint.

Since watchpoints are attached to symbols, modification to the objects contained within variables (e.g., by a list modification function see section 既存のリスト構造の変更) is not caught by this mechanism.

Additionally, C code can modify the value of variables directly, bypassing the watchpoint mechanism.

A minor limitation of this feature, again because it targets symbols, is that only variables of dynamic scope may be watched. This poses little difficulty, since modifications to lexical variables can be discovered easily by inspecting the code within the scope of the variable (unlike dynamic variables, which can be modified by any code at all, see section 変数のバインディングのスコーピングルール).

12.10 変数のバインディングのスコーピングルール

ある変数にたいするローカルバインディングを作成するとき、そのバインディングはプログラムの限られた一部だけに効果をもちます(ローカル変数を参照)。このセクションでは、これが正確には何を意味するかについて説明します。

ローカルバインディングはそれぞれ、個別にスコープ(scope: 範囲という意味)とエクステント(extent: これも範囲を意味する)をもちます。スコープはそのバインディングにアクセスできるのが、テキストのソースコードのどこ(where)であるかを示します。エクステントはプログラムの実行中に、そのバインディングが存在するのがいつ(when)であるかを示します。

デフォルトではEmacsが作成したローカルバインディングは、ダイナミックバインディング(dynamic binding)です。このようなバインディングはダイナミックスコープ(dynamic scope)をもち、それはプログラムの任意の範囲が、その変数バインディングにアクセスするかもしれないことを意味します。これはダイナミックエクステント(dynamic extent)ももっています。これはそのバインディング構造(letフォームのbodyなど)が実行される間だけ、そのバインディングが存続することを意味します。

Emacsはオプションでレキシカルバインディング(lexical binding)を作成することができます。レキシカルバインディングはレキシカルスコープ(lexical scope)をもち、これはその変数にたいするすべての参照が、バインディング構文内にテキスト的に配置されなければならないことを意味します⁷。レキシカルバインディングは不定エクステント(indefinite extent)ももっています。これはある状況下において、クロージャー(closures)と呼ばれるスペシャルオブジェクトにより、バインディング構造が実行を終えた後でさえも、存続し続けることを意味します。

以降のサブセクションでは、ダイナミックバインディングとレキシカルバインディング、およびEmacs Lispプログラムでレキシカルバインディングを有効にする方法についてより詳細に説明します。

12.10.1 ダイナミックバインディング		Emacs内でのローカル変数にたいするデフォルトのバインディング。
12.10.2 ダイナミックバインディングの正しい使用		ダイナミックバインディングによる問題を回避する。
12.10.3 レキシカルバインディング		ローカル変数にたいする他の種類のバインディング。
12.10.4 レキシカルバインディングの使用		レキシカルバインディングを有効にする方法。

12.10.1 ダイナミックバインディング

デフォルトでは、Emacsにより作成されるローカル変数のバインディングはダイナミックバインディングです。ある変数がダイナミックにバインドされていると、Lispプログラムの実行における任意のポイントでのカレントバインディングは、単にそのシンボルにたいしてもっとも最近作成されたダイナミックなローカルバインディング、またはそのようなローカルバインディングが存在しなければグローバルバインディングになります。

以下の例のように、ダイナミックバインディングはダイナミックスコープとダイナミックエクステントをもちます:

(defvar x -99)  ; xは初期値として-99を受け取る

(defun getx ()
  x)            ; この関数内ではxは自由に使用される

(let ((x 1))    ; xはダイナミックにバインドされている
  (getx))
     ⇒ 1

;; letフォームが終了した後に
;; xは前の値-99にリバートされる

(getx)
     ⇒ -99

関数getxはxを参照します。defun構文自体の中にxにたいするバインディングが存在しないという意味において、これはフリーな参照です。xが(ダイナミックに)バインドされているletフォーム内からgetxを呼び出すと、ローカル値(つまり1)が取得されます。しかしその後letフォームの外側からgetxを呼び出すと、グローバル値(つまり-99)が取得されます。

以下はsetqを使用してダイナミックに変数をバインドする例です:

(defvar x -99)      ; xは初期値として-99を受け取る

(defun addx ()
  (setq x (1+ x)))  ; xに1加算して新しい値をリターンする

(let ((x 1))
  (addx)
  (addx))
     ⇒ 3           ; addxを2回呼び出すとxに2回加算される

;; letフォームが終了した後に
;; xは前の値-99にリバートされる

(addx)
     ⇒ -98

Emacs Lispでのダイナミックバインディングは、シンプルな方法で実装されています。シンボルはそれぞれ、シンボルのカレントのダイナミック値(または値の不在)を指定する値セルをもちます。シンボルの構成要素を参照してください。あるシンボルがダイナミックなローカル値を与えられたとき、Emacsは値セルの内容(または値の不在)をスタックに記録して、新しいローカル値を値セルに格納します。バインディング構文が実行を終えたとき、Emacsはスタックから古い値をpopして値セルにそれを配置します。

12.10.2 ダイナミックバインディングの正しい使用

ダイナミックバインディングは、プログラムにたいしてテキスト的なローカルスコープ内で定義されていない変数を参照することを許容する、強力な機能です。しかし無制限に使用した場合には、プログラムの理解を困難にしてしまうこともあります。このテクニックを使用するために2つの明解な方法があります:

ある変数がグローバルな定義をもたなければ、ローカル変数としてバインディング構文内(その変数がバインドされるletフォームのbodyなどの場所)だけでそれを使用する。プログラムでこの慣習に一貫してしたがえば、プログラム内の他の場所で同じ変数シンボルを任意に使用しても、その変数の値に影響を与えたり、影響を受けることがなくなる。
Otherwise, define the variable with defvar, defconst (see section グローバル変数の定義), or defcustom (see section カスタマイズ変数の定義). Usually, the definition should be at top-level in an Emacs Lisp file. As far as possible, it should include a documentation string which explains the meaning and purpose of the variable. You should also choose the variable’s name to avoid name conflicts (see section Emacs Lispコーディングの慣習).
そうすればプログラム内のどこか別の場所で、それが何に影響するか確信をもって変数をバインドすることができます。その変数にどこで出会っても、(たとえば変数の定義がEmacsにロードされていればC-h vコマンドを通じて)定義を参照するのが簡単になります。Name Help in The GNU Emacs Manualを参照してください。

たとえばcase-fold-searchのようなカスタマイズ可能な変数にたいしてローカルバインディングを使用するのは一般的です:
```
(defun search-for-abc ()
  "Search for the string \"abc\", ignoring case differences."
  (let ((case-fold-search t))
    (re-search-forward "abc")))
```

12.10.3 レキシカルバインディング

Lexical binding was introduced to Emacs, as an optional feature, in version 24.1. We expect its importance to increase with time. Lexical binding opens up many more opportunities for optimization, so programs using it are likely to run faster in future Emacs versions. Lexical binding is also more compatible with concurrency, which was added to Emacs in version 26.1.

レキシカルにバインドされた変数はレキシカルスコープ(lexical scope)をもちます。これはその変数にたいする参照が、そのバインディング構文内にテキスト的に配置されなければならないことを意味しています。以下は例です (実際にレキシカルバインディングを有功にする方法は、レキシカルバインディングの使用を参照のこと):

(let ((x 1))    ; xはレキシカルにバインドされる
  (+ x 3))
     ⇒ 4

(defun getx ()
  x)            ; この関数内ではxは自由に使用される

(let ((x 1))    ; xはレキシカルにバインドされる
  (getx))
error→ Symbol's value as variable is void: x

ここではxはグローバル値をもちません。letフォーム内でレキシカルにバインドされたとき、この変数はletのテキスト境界内で使用できます。しかしこのlet内から呼び出されるgetx関数からは、getxの関数定義がletフォームの外側なので使用することができません。

レキシカルバインディングが機能する方法を説明します。バインディング構文はぞれぞれ、その構文内でローカル値にバインドする変数を指定する、レキシカル環境(lexical environment)を定義します。Lispの評価機能(Lisp evaluator)が、ある変数のカレント値を得たいときは、最初にレキシカル環境内を探します。そこで変数が指定されていなければ、ダイナミック値が格納されるシンボルの値セルを探します。

(内部的にはレキシカル環境はシンボルと値がペアになったalistでり、alistの最後の要素はコンスセルではなくシンボルtである。そのようなalistはフォームを評価するためのレキシカル環境を指定するために、eval関数の2番目の引数として渡すことができる。evalを参照のこと。しかしほとんどのEmacs Lispプログラムは、この方法で直接レキシカル環境を使用するべきではない。デバッガーのような特化されたプログラムだけが使用すること。)

レキシカルバインディングは不定エクステント(indefinite extent)をもちます。バインディング構造が終了した後でも、そのレキシカル環境はクロージャー(closures)と呼ばれるLispオブジェクト内に“保持”されるかもしれ、あせん。クロージャーはレキシカルバインディングが有効な、名前つきまたは無名(anonymous)の関数が作成されたときに作成されます。詳細はクロージャーを参照してください。

クロージャーが関数として呼び出されたとき、その関数の定義内のレキシカル変数にたいする任意の参照は、維持されたレキシカル環境を使用します。以下は例です:

(defvar my-ticker nil)   ; クロージャーを格納するために
                         ; この変数を使用する

(let ((x 0))             ; xはレキシカルにバインドされる
  (setq my-ticker (lambda ()
                    (setq x (1+ x)))))
    ⇒ (closure ((x . 0) t) ()
          (setq x (1+ x)))

(funcall my-ticker)
    ⇒ 1

(funcall my-ticker)
    ⇒ 2

(funcall my-ticker)
    ⇒ 3

x                        ; xはグローバル値をもたないことに注意
error→ Symbol's value as variable is void: x

letバインディングは、内部に変数xをもつレキシカル環境を定義して、変数は0にローカルにバインドされます。このバインディング構文内でxを1増加して、増加された値をリターンするクロージャーを定義しています。このラムダ式は自動的にクロージャーとなり、たとえlet構文を抜けた後でも、その内部ではレキシカル環境が存続します。クロージャーを評価するときは、毎回レキシカル環境内のxのバインディングが使用されて、xが加算されます。

シンボルオブジェクト自体に束縛されるダイナミック変数と異なり、レキシカル変数とシンボルの関係はインタープリター(かコンパイラー)内にのみ存在します。したがって(symbol-value、boundp、setのような)シンボル引数を受け取る関数ができるのは、変数のダイナミックなバインディング(そのシンボルの値セルの内容)の取得と変更だけです。

12.10.4 レキシカルバインディングの使用

Emacs LispファイルのロードやLispバッファーを評価するとき、バッファーローカルな変数lexical-bindingが非nilなら、レキシカルバインディングが有効になります:

Variable: lexical-binding: このバッファーローカルな変数が非nilなら、Emacs Lispファイルとバッファーはダイナミックバインディングではなくレキシカルバインディングを使用して評価される(しかし特別な変数はダイナミックにバインドされたまま。以下を照)。nilならすべてのローカル変数にたいしてダイナミックバインディングが使用される。この変数は、通常はファイルローカル変数として、Emacs Lispファイル全体にたいしてセットされる(ファイルローカル変数を参照)。他のファイルローカル変数などとは異なり、ファイルの最初の行でセットされなければならないことに注意。

eval呼び出しを使用してEmacs Lispコードを直接評価するとき、evalのlexical引数が非nilなら、レキシカルバインディングが有効になります。evalを参照してください。

レキシカルバインディングが有効な場合でも、特定の変数はダイナミックにバインドされたままです。これらはスペシャル変数(special variable)と呼ばれます。defvar、defcustom、defconstで定義されたすべての変数はスペシャル変数です(グローバル変数の定義を参照)。その他のすべての変数はレキシカルバインディングの対象になります。

Using defvar without a value, it is possible to bind a variable dynamically just in one file, or in just one part of a file while still binding it lexically elsewhere. For example:

(let (_)
  (defvar x)      ; Let-bindings of x will be dynamic within this let.
  (let ((x -99))  ; This is a dynamic binding of x.
    (defun get-dynamic-x ()
      x)))

(let ((x 'lexical)) ; This is a lexical binding of x.
  (defun get-lexical-x ()
    x))

(let (_)
  (defvar x)
  (let ((x 'dynamic))
    (list (get-lexical-x)
          (get-dynamic-x))))
    ⇒ (lexical dynamic)

Function: special-variable-p symbol: この関数はsymbolがスペシャル変数(つまり変数がdefvar、defcustom、defconstによる定義をもつ)なら非nilをリターンする。、それ以外ならリターン値はnil。

関数内での通常の引数としてのスペシャル変数の使用は、推奨されません。レキシカルバインディングモードが有効なときにこれを行うと、(あるときはレキシカルバインディング、またあるときはダイナミックバインディングのような)不定な動作が起こります。

Emacs Lispプログラムをレキシカルバインディングに変換するのは簡単です。最初にEmacs Lispソースファイルのヘッダー行でlexical-bindingをtにして、ファイルローカル変数を追加します(ファイルローカル変数を参照)。次に意図せずレキシカルにバインドしてしまわないように、ダイナミックなバインドをもつ必要がある変数が変数定義をもつことを各変数ごとにチェックします。

どの変数が変数定義をもつ必要があるか見つけるシンプルな方法は、ソースファイルをバイトコンパイルすることです。バイトコンパイルを参照してください。letフォームの外側で非スペシャル変数が使用されていれば、バイトコンパイラーはフリーな変数にたいする参照や割り当てについて警告するでしょう。非スペシャル変数がバインドされているがletフォーム内で使用されていなければ、バイトコンパイラーは使用されないレキシカル変数に関して警告するでしょう。バイトコンパイラーは、スペシャル変数を関数の引数として使用している場合も問題を警告します。

(To silence byte-compiler warnings about unused variables, just use a variable name that starts with an underscore. The byte-compiler interprets this as an indication that this is a variable known not to be used.)

12.11 バッファーローカル変数

グローバルおよびローカルな変数バインディングは、いずれかの形式をほとんどのプログラミング言語で見つけることができます。しかしEmacsは1つのバッファーだけに適用されるバッファーローカル(buffer-local)なバインディング用に、普通には存在しない類の変数バインディングもサポートしています。ある変数にたいして異なるバッファーごとに別の値をもつのは、カスタマイズでの重要な手法です(変数は端末ごとにローカルなバインディングをもつこともできる。複数の端末を参照)。

12.11.1 バッファーローカル変数の概要

バッファーローカル変数は特定のバッファーに関連づけられた、バッファーローカルなバインディングをもちます。このバインディングはそのバッファーがカレントのときに効果をもち、カレントでないときには効果がありません。バッファーローカルなバインディングが効力をもつときにその変数をセットすると、そのバインディングは新しい値をもちますが他のバインディングは変更されません。これはバッファーローカルなバインディングを作成したバッファーだけで変更が見えることを意味します。

その変数にたいする特定のバッファーに関連しない通常のバインディングは、デフォルトバインディング(default binding)と呼ばれます。これはほとんどの場合はグローバルバインディングです。

変数はあるバッファーではバッファーローカルなバインディングをもつことができ、他のバッファーではもたないことができます。デフォルトバインディングは、その変数にたいして自身のバインディングをもたないすべてのバッファーで共有されます(これには新たに作成されたバッファーが含まれる)。ある変数にたいして、その変数のバッファーローカルなバインディングをもたないバッファーでその変数をセットすると、それによりデフォルトバインディングがセットされるので、デフォルトバインディングを参照するすべてのバッファーで新しい値を見ることになります。

バッファーローカルなバインディングのもっとも一般的な使用は、メジャーモードがコマンドの動作を制御するために変数を変更する場合です。たとえばCモードやLispモードは、空行だけがパラグラフの区切りになるように変数paragraph-startをセットします。これらのモードは、CモードやLispモードになるようなバッファー内でこの変数をバッファーローカルにすることでこれを行って、その後そのモードにたいする新しい値をセットします。メジャーモードを参照してください。

バッファーローカルなバインディングを作成する通常の方法は、make-local-variableによる方法で、これは通常はメジャーモードが使用します。これはカレントバッファーだけに効果があります。その他すべてのバッファー(まだ作成されていないバッファーを含む)は、それらのバッファー自身が明示的にバッファーローカルなバインディングを与えるまでデフォルト値を共有し続けます。

変数を自動的にバッファーローカルになるようにマークする、より強力な操作はmake-variable-buffer-localを呼び出すことにより行われます。これはたとえその変数がまだ作成されていなくても、変数をすべてのバッファーにたいしてローカルにすると考えることができます。より正確には変数を自動的にセットすることにより、その変数がカレントバッファーにたいしてローカルでなくても、変数をローカルにする効果があります。すべてのバッファーは最初は通常のようにデフォルト値を共有しますが、変数をセットすることでカレントバッファーにたいしてバッファーローカルなバインディングを作成します。新たな値はバッファーローカルなバインディングに格納され、デフォルトバインディングは変更されずに残ります。これは任意のバッファーでsetqによりデフォルト値を変更できないことを意味します。変更する唯一の方法はsetq-defaultだけです。

警告: ある変数が1つ以上のバッファーでバッファーローカルなバインディングをもつ際に、letはそのとき効力がある変数のバインディングをリバインドします。たとえばカレントバッファーがバッファーローカルな値をもつなら、letは一時的にそれをリバインドします。効力があるバッファーローカルなバインディングが存在しなければletはデフォルト値をリバインドします。letの内部で、別のバインディングが効力をもつ別のバッファーをカレントバッファーにすると、それ以上letバインディングを参照できなくなります。他のバッファーにいる間にletを抜けると、(たとえそれが正しくても)バインディングの解消を見ることはできません。以下にこれを示します:

(setq foo 'g)
(set-buffer "a")
(make-local-variable 'foo)

(setq foo 'a)
(let ((foo 'temp))
  ;; foo ⇒ 'temp  ; バッファー‘a’内でのletバインディング
  (set-buffer "b")
  ;; foo ⇒ 'g     ; fooは‘b’にたいしてローカルではないためグローバル値
  body…)

foo ⇒ 'g        ; exitによりバッファー‘a’のローカル値が復元されるが
                 ; バッファー‘b’では見ることができない

(set-buffer "a") ; ローカル値が復元されたことを確認
foo ⇒ 'a

body内のfooにたいする参照は、バッファー‘b’のバッファーローカルなバインディングにアクセスすることに注意してください。

あるファイルがローカル変数の値をセットする場合、これらの変数はファイルをvisitするときバッファーローカルな値になります。File Variables in The GNU Emacs Manualを参照してください。

バッファーローカル変数を端末ローカル(terminal-local)にすることはできません(複数の端末を参照)。

12.11.2 バッファーローカルなバインディングの作成と削除

Command: make-local-variable variable

この関数はカレントバッファー内で、variable(シンボル)にたいするバッファーローカルなバインディングを作成する。他のバッファーは影響を受けない。リターンされる値はvariable。

variableのバッファーローカルな値は、最初は以前にvariableがもっていた値と同じ値をもつ。variableがvoidのときはvoidのまま。

;; バッファー‘b1’で行う:
(setq foo 5)                ; すべてのバッファーに影響する。
     ⇒ 5

(make-local-variable 'foo)  ; ‘b1’内でローカルになった
     ⇒ foo

foo                         ; 値は変更されない
     ⇒ 5

(setq foo 6)                ; ‘b1’内で値を変更
     ⇒ 6

foo
     ⇒ 6

;; バッファー‘b2’では、値は変更されていない
(with-current-buffer "b2"
  foo)
     ⇒ 5

変数をletバインディングでバッファーローカルにしても、letへの出入り時の両方でこれを行うバッファーがカレントでなければ信頼性はない。これはletがバインディングの種類を区別しないからである。letに解るのはバインディングが作成される変数だけである。

It is an error to make a constant or a read-only variable buffer-local. See section 変更不可な変数.

変数が端末ローカル(複数の端末を参照)なら、この関数はエラーをシグナルする。そのような変数はバッファーローカルなバインディングをもつことができない。

警告: フック変数にたいしてmake-local-variableを使用しないこと。フック変数はadd-hookかremove-hookのlocal引数を使用すると、必要に応じて自動でバッファーローカルになる。

Macro: setq-local variable value: このマクロはカレントバッファー内でvariableにたいするバッファーローカルなバインディングを作成して、それにバッファーローカルな値valueを与える。このマクロはmake-local-variableに続けてsetqを呼び出すのと同じ。variableはクォートされていないシンボル。

Command: make-variable-buffer-local variable

このコマンドはvariable(シンボル)が自動的にバッファーローカルになるようにマークするので、それ以降にその変数へのセットを試みると、その時点でカレントのバッファーにローカルになる。しばしば混乱を招くmake-local-variableとは異なり、これが取り消されることはなく、すべてのバッファー内での変数の挙動に影響する。

この機能特有の欠点は、(letやその他のバインディング構文による)変数のバインディングが、その変数にたいするバッファーローカルなバインディングを作成しないことである。(setやsetqによる)変数のセットだけは、その変数がカレントバッファーで作成されたletスタイルのバインディングをもたないので、ローカルなバインディングを作成する。

variableがデフォルト値をもたない場合、このコマンドの呼び出しはnilのデフォルト値を与える。variableがすでにデフォルト値をもつなら、その値は変更されずに残る。それ以降にvariableにたいしてmakunboundを呼び出すと、バッファーローカル値をvoidにして、デフォルト値は影響を受けずに残る。

▼リターン値はvariable。

It is an error to make a constant or a read-only variable buffer-local. See section 変更不可な変数.

警告: ユーザーオプション変数では、ユーザーは異なるバッファーにたいして異なるカスタマイズを望むかもしれないので、make-variable-buffer-localを使うべきだと決め込むべきではない。ユーザーは望むなら任意の変数をローカルにできる。その選択の余地を残すほうがよい。

make-variable-buffer-localを使用すべきなのは、複数のバッファーが同じバインディングを共有しないことが自明な場合である。たとえばバッファーごとに個別な値をもつことに依存するLispプログラム内の内部プロセスにたいして変数が使用されるときは、make-variable-buffer-localの使用が最善の解決策になるかもしれない。

Macro: defvar-local variable value &optional docstring: このマクロはvariableを初期値valueとdocstringの変数として定義して、それを自動的にバッファーローカルとマークする。これはdefvarの後につづけてmake-variable-buffer-localを呼び出すのと同じ。variableはクォートされていないシンボル。

Function: local-variable-p variable &optional buffer: これはvariableがバッファーbuffer(デフォルトはカレントバッファー)内でバッファーローカルならt、それ以外はnilをリターンする。

Function: local-variable-if-set-p variable &optional buffer: これはvariableがバッファーbuffer内でバッファーローカル値をもつ、または自動的にバッファーローカルになるならt、それ以外はnilをリターンする。bufferが省略またはnilの場合のデフォルトはカレントバッファー。

Function: buffer-local-value variable buffer: この関数はバッファーbuffer内の、variable(シンボル)のバッファーローカルなバインディングをリターンする。variableがバッファーbuffer内でバッファーローカルなバインディングをもたなければ、かわりにvariableのデフォルト値(バッファーローカル変数のデフォルト値を参照)をリターンする。

Function: buffer-local-variables &optional buffer

この関数はバッファーbuffer内のバッファーローカル変数を表すリストをリターンする(bufferが省略された場合はカレントバッファーが使用される)。リストの各要素は通常は(sym . val)という形式をもつ。ここでsymはバッファーローカル変数(シンボル)、valはバッファーローカル値。しかしbuffer内のある変数のバッファーローカルなバインディングがvoidなら、その変数に対応するリスト要素は単にsymとなる。

(make-local-variable 'foobar)
(makunbound 'foobar)
(make-local-variable 'bind-me)
(setq bind-me 69)

(setq lcl (buffer-local-variables))
    ;; 最初はすべてのバッファー内でローカルなビルトイン変数:
⇒ ((mark-active . nil)
    (buffer-undo-list . nil)
    (mode-name . "Fundamental")
    …

    ;; 次にビルトインでないバッファーローカル変数
    ;; This one is buffer-local and void:
    foobar
    ;; これはバッファーローカルでvoidではない:
    (bind-me . 69))

このリスト内のコンスセルのCDRに新たな値を格納しても、その変数のバッファーローカル値は変化しないことに注意。

Command: kill-local-variable variable

この関数はカレントバッファー内のvariable(シンボル)にたいするバッファーローカルなバインディング(もしあれば)を削除する。その結果として、このバッファー内でvariableのデフォルトバインディングが可視になる。これは通常はvariableの値を変更する。デフォルト値は削除されたバッファーローカル値とは異なるのが普通だからである。

セットしたとき自動的にバッファーローカルになる変数のバッファーローカルなバインディングをkillすると、これによりカレントバッファー内でデフォルト値が可視になる。しかし変数を再度セットすると、その変数にたいするバッファーローカルなバインディングが再作成される。

kill-local-variableはvariableをreturnします。

この関数はコマンドである。なぜならバッファーローカル変数のインタラクティブな作成が有用な場合があるように、あるバッファーローカル変数のインタラクティブなkillが有用な場合があるからである。

Function: kill-all-local-variables

この関数はpermanent(永続的)とマークされた変数とpermanent-local-hookプロパティーに非nilをもつローカルフック関数(フックのセットSetting Hooksを参照)を除き、カレントバッファーのすべてのバッファーローカルなバインディングを解消する。結果として、そのバッファーのほとんどの変数がデフォルト値を参照するようになる。

この関数はそのバッファーに関連する他の特定の情報もリセットする。これはローカルキーマップをnil、構文テーブルを(standard-syntax-table)の値、caseテーブルを(standard-case-table)、abbrevテーブルをfundamental-mode-abbrev-tableの値にセットする。

この関数が1番最初に行うのはノーマルフックchange-major-mode-hook(以下参照)の実行である。

すべてのメジャーモードコマンドは、Fundamentalモードにスイッチする効果をもち、以前のメジャーモードのほとんどの効果を消去する、この関数を呼び出すことによって開始されます。この関数が処理を行うのを確実にするために、メジャーモードがセットする変数はpermanentとマークすべきではない。

kill-all-local-variables returns nil.

Variable: change-major-mode-hook

関数kill-all-local-variablesは、何か他のことを行う前にまずこのノーマルフックを実行する。この関数はメジャーモードにたいして、ユーザーが他のメジャーモードにスイッチした場合に行われる何か特別なことを準備する方法を与える。この関数はユーザーがメジャーモードを変更した場合に忘れられるべき、バッファー固有のマイナーモードにたいしても有用。

最善の結果を得るために、この変数をバッファーローカルにすれば、処理が終了したときに消えるので、以降のメジャーモードに干渉しなくなる。フックを参照のこと。

変数名(シンボル)が非nilのpermanent-localプロパティーをもつなら、そのバッファーローカル変数はpermanent(永続的)です。そのような変数はkill-all-local-variablesの影響を受けず、したがってメジャーモードの変更によりそれらのローカルバインディングは作成されません。permanentなローカル変数はファイルの内容を編集する方法ではなく、どこから読み込んだファイルか、あるいはどのように保存するかといったことに関連するデータに適しています。

12.11.3 バッファーローカル変数のデフォルト値

バッファーローカルなバインディングをもつ変数のグローバル値もデフォルト値(default)値と呼ばれます。なぜならその変数にたいしてカレントバッファーや選択されたフレームもバインディングをもたなければ、その値が常に効果をもつからです。

関数default-valueとsetq-defaultは、カレントバッファーがバッファーローカルなバインディングをもつかどうかに関わらず、その変数のデフォルト値にアクセスまたは変更します。たとえばほとんどのバッファーにたいして、paragraph-startのデフォルトのセッティングを変更するために、setq-defaultを使用できます。そしてこの変数にたいするバッファーローカルな値をもつCモードやLispモードにいるときでさえ、これは機能します。

スペシャルフォームdefvarとdefconstもバッファーローカルな値ではなく、(もし変数にセットする場合は)デフォルト値をセットします。

Function: default-value symbol: この関数はsymbolのデフォルト値をリターンする。これはこの変数にたいして独自の値をもたないバッファーやフレームから参照される値である。symbolがバッファーローカルでなければ、これはsymbol-value(変数の値へのアクセスを参照)と同じ。

Function: default-boundp symbol

関数default-boundpはsymbolのデフォルト値がvoidでないか報告する。(default-boundp 'foo)がnilをリターンした場合には(default-value 'foo)はエラーになる。

default-boundpはdefault-value、boundpはsymbol-valueにたいする述語である。

Special Form: setq-default [symbol form]…

このスペシャルフォームは各symbolに新たなデフォルト値として、対応するformを評価した結果を与える。これはsymbolを評価しないがformは評価する。setq-defaultフォームの値は最後のformの値。

カレントバッファーにたいしてsymbolがバッファーローカルでなく、自動的にバッファーローカルにマークされていなければ、setq-defaultはsetqと同じ効果をもつ。カレントバッファーにたいしてsymbolがバッファーローカルなら、(バッファーローカルな値をもたない)他のバッファーから参照できる値を変更するが、それはカレントバッファーが参照する値ではない。

;; バッファー‘foo’で行う:
(make-local-variable 'buffer-local)
     ⇒ buffer-local

(setq buffer-local 'value-in-foo)
     ⇒ value-in-foo

(setq-default buffer-local 'new-default)
     ⇒ new-default

buffer-local
     ⇒ value-in-foo

(default-value 'buffer-local)
     ⇒ new-default

;; (新しい)バッファー‘bar’で行う:
buffer-local
     ⇒ new-default

(default-value 'buffer-local)
     ⇒ new-default

(setq buffer-local 'another-default)
     ⇒ another-default

(default-value 'buffer-local)
     ⇒ another-default

;; バッファー‘foo’に戻って行う:
buffer-local
     ⇒ value-in-foo
(default-value 'buffer-local)
     ⇒ another-default

Function: set-default symbol value

この関数はsetq-defaultと似ているが、symbolは通常の引数として評価される。

(set-default (car '(a b c)) 23)
     ⇒ 23

(default-value 'a)
     ⇒ 23

A variable can be let-bound (see section ローカル変数) to a value. This makes its global value shadowed by the binding; default-value will then return the value from that binding, not the global value, and set-default will be prevented from setting the global value (it will change the let-bound value instead). The following two functions allow to reference the global value even if it’s shadowed by a let-binding.

Function: default-toplevel-value symbol: This function returns the top-level default value of symbol, which is its value outside of any let-binding.

(defvar variable 'global-value)
    ⇒ variable

(let ((variable 'let-binding))
  (default-value 'variable))
    ⇒ let-binding

(let ((variable 'let-binding))
  (default-toplevel-value 'variable))
    ⇒ global-value

Function: set-default-toplevel-value symbol value: This function sets the top-level default value of symbol to the specified value. This comes in handy when you want to set the global value of symbol regardless of whether your code runs in the context of symbol’s let-binding.

12.12 ファイルローカル変数

ファイルにローカル変数の値を指定できます。そのファイルをvisitしているバッファー内で、これらの変数にたいしてバッファーローカルなバインディングを作成するために、Emacsはこれらを使用します。ファイルローカル変数の基本的な情報については、Local Variables in Files in The GNU Emacs Manualを参照してください。このセクションではファイルローカル変数が処理される方法に影響する関数と変数を説明します。

ファイルローカル変数が勝手に関数や、後で呼び出されるLisp式を指定できたら、ファイルのvisitによってEmacsが乗っ取られてしまうかもしれません。Emacsは既知のファイルローカル変数だけにたいして、指定された値が安全だと自動的にセットすることにより、この危険から保護します。これ以外のファイルローカル変数は、ユーザーが同意した場合のみセットされます。

追加の安全策としてEmacsがファイルローカル変数を読み込むとき、一時的にread-circleをnilにバインドします(入力関数を参照)。これは循環認識と共有されたLisp構造からLispリーダーを保護します(循環オブジェクトの読み取り構文を参照)。

User Option: enable-local-variables

この変数はファイルローカル変数を処理するかどうかを制御する。以下の値が利用できる:

t(デフォルト): 安全な変数をセット、安全でない変数は問い合わせる(1回)。
:safe: 安全な変数だけをセット、問い合わせはしない。
:all: 問い合わせをせずに、すべての変数をセット。
nil: 変数をセットしない。
その他: すべての変数にたいして問い合わせる(1回)。

Variable: inhibit-local-variables-regexps: これは正規表現のリストである。ファイルがこのリストの要素にマッチする名前をもつなら、すべてのファイルローカル変数のフォームはスキャンされない。どんなときにこれを使いたいかの例は、Emacsがメジャーモードを選択する方法を参照のこと。

Function: hack-local-variables &optional handle-mode

この関数はカレントバッファーの内容により指定された任意のローカル変数にたいしてパースを行い、適切にバインドと評価を行う。変数enable-local-variablesはここでも効果をもつ。しかしこの関数は‘-*-’行の、‘mode:’ローカル変数を探さない。set-auto-modeはこれを行ってenable-local-variablesも考慮する(Emacsがメジャーモードを選択する方法を参照)。

この関数はfile-local-variables-alist内に格納されたalistを調べて、各ローカル変数を順に適用することにより機能する。この関数は変数に適用する前(か後)に、before-hack-local-variables-hook(かhack-local-variables-hook)を呼び出す。alistが非nilの場合のみ、事前のフック(before-hook)を呼び出し、その他のフックは常に呼び出す。この関数はそのバッファーがすでにもつメジャーモードと同じメジャーモードが指定された場合は‘mode’要素を無視する。

If the optional argument handle-mode is t, then all this function does is return a symbol specifying the major mode, if the ‘-*-’ line or the local variables list specifies one, and nil otherwise. It does not set the mode or any other file-local variable. If handle-mode has any value other than nil or t, any settings of ‘mode’ in the ‘-*-’ line or the local variables list are ignored, and the other settings are applied. If handle-mode is nil, all the file local variables are set.

Variable: file-local-variables-alist: このバッファーローカルな変数は、ファイルローカル変数のセッティングのalistを保持する。alistの各要素は(var . value)という形式で、varはローカル変数のシンボル、valueはその値である。Emacsがファイルをvisitするとき、最初にすべてのファイルローカル変数をこのalistに収集して、その後で変数に1つずつ関数hack-local-variablesを適用する。

Variable: before-hack-local-variables-hook: Emacsはfile-local-variables-alistに格納されたファイルローカル変数を適用する直前にこのフックを呼び出す。

Variable: hack-local-variables-hook: Emacsはfile-local-variables-alistに格納されたファイルローカル変数を適用し終えた直後にこのフックを呼び出す。

ある変数にたいしてsafe-local-variableプロパティーによって安全な値を指定できます。このプロパティーは引数を1つとる関数です。与えられた値にたいして、その関数が非nilをリターンしたらその値は安全です。一般的に目にするファイル変数の多くは、safe-local-variableプロパティーをもちます。これらのファイル変数にはfill-column、fill-prefix、indent-tabs-modeが含まれます。ブーリーン値の変数にたいしては、プロパティーの値にbooleanpを使用します。

When defining a user option using defcustom, you can set its safe-local-variable property by adding the arguments :safe function to defcustom (see section カスタマイズ変数の定義). However, a safety predicate defined using :safe will only be known once the package that contains the defcustom is loaded, which is often too late. As an alternative, you can use the autoload cookie (see section autoload) to assign the option its safety predicate, like this:

;;;###autoload (put 'var 'safe-local-variable 'pred)

The safe value definitions specified with autoload are copied into the package’s autoloads file (loaddefs.el for most packages bundled with Emacs), and are known to Emacs since the beginning of a session.

User Option: safe-local-variable-values

この変数はある変数の値が安全であることをマークする、別の方法を提供する。これはコンスセル(var . val)のリストでありvarは変数名、valはその変数にたいして安全な値である。

Emacsが一連のファイルローカル変数にしたがうかどうかユーザーに尋ねるとき、ユーザーはそれらの変数が安全だとマークすることができる。安全とマークするとsafe-local-variable-valuesにこれらのvariable/valueペアーが追加されて、ユーザーのカスタムファイルに保存する。

Function: safe-local-variable-p sym val: この関数は上記の条件に基づき、symに値valを与えても安全ななら非nilをリターンする。

いくつかの変数は危険(risky)だと判断されます。ある変数が危険なら、その変数がsafe-local-variable-valuesに自動的に追加されることはありません。ユーザーがsafe-local-variable-valuesを直接カスタマイズすることで明示的に値を許さない限り、危険な変数をセットする前にEmacsは常に確認を求めます。

名前が非nilのrisky-local-variableプロパティーをもつすべての変数は危険だと判断されます。defcustomを使用してユーザーオプションを定義するとき、defcustomに引数:risky valueを追加することにより、ユーザーオプションにrisky-local-variableプロパティーをセットできます。それに加えて名前が‘-command’、‘-frame-alist’、‘-function’、‘-functions’、‘-hook’、‘-hooks’、‘-form’、‘-forms’、‘-map’、‘-map-alist’、‘-mode-alist’、‘-program’、‘-predicate’で終わるすべての変数は自動的に危険だと判断されます。後に数字をともなう変数‘font-lock-keywords’と‘font-lock-keywords’、さらには‘font-lock-syntactic-keywords’も危険だと判断されます。

Function: risky-local-variable-p sym: この関数はsymが上記の条件にもとづき危険な変数なら非nilをリターンする。

Variable: ignored-local-variables: この変数はファイルによりローカル値を与えらるべきではない変数のリストを保持する。これらの変数に指定された任意の値は、完全に無視される。

“変数”‘Eval:’も抜け道になる可能性があるので、Emacsは通常はそれを処理する前に確認を求めます。

User Option: enable-local-eval: この変数は‘-*-’の行中、またはvisitされるファイル内のローカル変数リストにたいする、‘Eval:’の処理を制御する。値tは無条件に実行し、nilはそれらを無視することを意味します。それ以外なら各ファイルにたいして何を行うか、ユーザーに確認を求めることを意味する。デフォルト値はmaybe。

User Option: safe-local-eval-forms: この変数はファイルローカル変数リスト内で‘Eval:’“変数”が見つかった際に評価しても安全な式のリストを保持する。

式が関数呼び出しであり、その関数がsafe-local-eval-functionプロパティーをもつなら、その式の評価が安全かどうかはそのプロパティー値が決定します。プロパティー値はその式をテストするための述語(predicate)、そのような述語のリスト(成功した述語があれば安全)、またはt(引数が定数である限り常に安全)を指定できます。

テキストプロパティーには、それらの値に関数呼び出しを含めることができるので抜け道になる可能性があります。したがってEmacsはファイルローカル変数にたいして指定された文字列値から、テキストプロパティーを取り除きます。

12.13 ディレクトリーローカル変数

ディレクトリーは、そのディレクトリー内のすべてのファイルに共通なローカル変数値を指定することができます。Emacsはそのディレクトリー内の任意のファイルをvisitしているバッファー内で、それらの変数にたいするバッファーローカルなバインディングを作成するためにこれを使用します。これはそのディレクトリー内のファイルが何らかのプロジェクトに属していて、同じローカル変数を共有するときなどに有用です。

ディレクトリーローカル変数を指定するために2つの異なる方法があります: 1つは特別なファイルにそれを記述する方法、もう1つはそのディレクトリーにプロジェクトクラス(project class)を定義する方法です。

Constant: dir-locals-file: This constant is the name of the file where Emacs expects to find the directory-local variables. The name of the file is .dir-locals.el⁸. A file by that name in a directory causes Emacs to apply its settings to any file in that directory or any of its subdirectories (optionally, you can exclude subdirectories; see below). If some of the subdirectories have their own .dir-locals.el files, Emacs uses the settings from the deepest file it finds starting from the file’s directory and moving up the directory tree. This constant is also used to derive the name of a second dir-locals file .dir-locals-2.el. If this second dir-locals file is present, then that is loaded instead of .dir-locals.el. This is useful when .dir-locals.el is under version control in a shared repository and cannot be used for personal customizations. The file specifies local variables as a specially formatted list; see Per-directory Local Variables in The GNU Emacs Manual, for more details.

Function: hack-dir-local-variables: この関数は.dir-locals.elファイルを読み込み、そのディレクトリー内の任意のファイルをvisitしているバッファーにローカルなfile-local-variables-alist内に、それらを適用することなくディレクトリーローカル変数を格納する。この関数はディレクトリーローカルなセッティングもdir-locals-class-alist(.dir-locals.elファイルが見つかったディレクトリーにたいする特別なクラスを定義する)内に格納する。この関数は以下で説明するように、dir-locals-set-class-variablesとdir-locals-set-directory-classを呼び出すことにより機能する。

Function: hack-dir-local-variables-non-file-buffer: この関数はディレクトリーローカル変数を探して、即座にそれらをカレントバッファーに適用する。これはDiredバッファーのような、非ファイルバッファーをディレクトリーローカル変数のセッティングにしたがわせるために、モードコマンド呼び出しの中から呼び出されることを意図したものである。非ファイルバッファーにたいしては、Emacsはdefault-directoryとその親ディレクトリーの中から、ディレクトリーローカル変数を探す。

Function: dir-locals-set-class-variables class variables

この関数はclassという名前がつけられたシンボルにたいして、一連の変数セッティングを定義する。ユーザーは後からこのクラスを1つ以上のディレクトリーに割り当てることができる。そしてEmacsはこれらの変数セッティングを、それらのディレクトリー内のすべてのファイルに適用するだろう。variables内のリストは2つの形式 — (major-mode . alist)か(directory . list) — のいずれかをもつことができる。1番目の形式ではそのファイルのバッファーがmajor-modeを継承するモードに切り替わるときに、連想リストalist内のすべての変数が適用される。alistは(name . value)という形式。major-modeにたいする特別な値nilは、そのセッティングが任意のモードに適用できることを意味する。alist内では特別なnameとして、subdirsを使用することができる。連想値がnilなら、alistは関連するディレクトリー内のファイルだけに適用され、それらのサブディレクトリーには適用されない。

variablesの2番目の形式では、directoryがそのファイルのディレクトリーの最初のサブディレクトリーなら、上記のルールにしたがいlistが再帰的に適用される。listはこの関数のvariablesで指定できる2つの形式のうち1つを指定する。

Function: dir-locals-set-directory-class directory class &optional mtime

この関数はdirectoryとサブディレクトリー内のすべてのファイルにclassを割り当てる。その後、classにたいして指定されたすべての変数セッティングは、directoryとその子ディレクトリー内でvisitされたすべてのファイルに適用される。classは事前にdir-locals-set-class-variablesで定義されていなければならない。

Emacsが.dir-locals.elファイルからディレクトリー変数をロードする際、内部的にこの関数を使用する。その場合、オプションの引数mtimeはファイルの修正日時(modification time。file-attributesによりリターンされる)を保持する。Emacsは記憶されたローカル変数がまだ有効化チェックするために、この日時を使用する。ファイルを介さず直接クラスを割り当てる場合、この引数はnilになる。

Variable: dir-locals-class-alist: このalistはクラスシンボル(class symbol)とそれに関連づけられる変数のセッティングを保持する。これはdir-locals-set-class-variablesにより更新される。

Variable: dir-locals-directory-cache: このalistはディレクトリー名、それらに割り当てられたクラス名、およびこのエントリーに関連するディレクトリーローカル変数ファイルの修正日時を保持する。関数dir-locals-set-directory-classはこのlistを更新する。

Variable: enable-dir-local-variables: nilならディレクトリーローカル変数は無視される。この変数はファイルローカル変数(ファイルローカル変数を参照)にはしたがうが、ディレクトリーローカル変数は無視したいモードにたいして有用かもしれない。

12.14 Connection Local Variables

Connection-local variables provide a general mechanism for different variable settings in buffers with a remote connection. They are bound and set depending on the remote connection a buffer is dedicated to.

Function: connection-local-set-profile-variables profile variables

This function defines a set of variable settings for the connection profile, which is a symbol. You can later assign the connection profile to one or more remote connections, and Emacs will apply those variable settings to all process buffers for those connections. The list in variables is an alist of the form (name . value). Example:

(connection-local-set-profile-variables
  'remote-bash
  '((shell-file-name . "/bin/bash")
    (shell-command-switch . "-c")
    (shell-interactive-switch . "-i")
    (shell-login-switch . "-l")))

(connection-local-set-profile-variables
  'remote-ksh
  '((shell-file-name . "/bin/ksh")
    (shell-command-switch . "-c")
    (shell-interactive-switch . "-i")
    (shell-login-switch . "-l")))

(connection-local-set-profile-variables
  'remote-null-device
  '((null-device . "/dev/null")))

Variable: connection-local-profile-alist: This alist holds the connection profile symbols and the associated variable settings. It is updated by connection-local-set-profile-variables.

Function: connection-local-set-profiles criteria &rest profiles

This function assigns profiles, which are symbols, to all remote connections identified by criteria. criteria is a plist identifying a connection and the application using this connection. Property names might be :application, :protocol, :user and :machine. The property value of :application is a symbol, all other property values are strings. All properties are optional; if criteria is nil, it always applies. Example:

(connection-local-set-profiles
  '(:application 'tramp :protocol "ssh" :machine "localhost")
  'remote-bash 'remote-null-device)

(connection-local-set-profiles
  '(:application 'tramp :protocol "sudo"
    :user "root" :machine "localhost")
  'remote-ksh 'remote-null-device)

If criteria is nil, it applies for all remote connections. Therefore, the example above would be equivalent to

(connection-local-set-profiles
  '(:application 'tramp :protocol "ssh" :machine "localhost")
  'remote-bash)

(connection-local-set-profiles
  '(:application 'tramp :protocol "sudo"
    :user "root" :machine "localhost")
  'remote-ksh)

(connection-local-set-profiles
  nil 'remote-null-device)

Any connection profile of profiles must have been already defined by connection-local-set-profile-variables.

Variable: connection-local-criteria-alist: This alist contains connection criteria and their assigned profile names. The function connection-local-set-profiles updates this list.

Function: hack-connection-local-variables criteria

This function collects applicable connection-local variables associated with criteria in connection-local-variables-alist, without applying them. Example:

(hack-connection-local-variables
  '(:application 'tramp :protocol "ssh" :machine "localhost"))

connection-local-variables-alist
     ⇒ ((null-device . "/dev/null")
        (shell-login-switch . "-l")
        (shell-interactive-switch . "-i")
        (shell-command-switch . "-c")
        (shell-file-name . "/bin/bash"))

Function: hack-connection-local-variables-apply criteria: This function looks for connection-local variables according to criteria, and immediately applies them in the current buffer.

Macro: with-connection-local-profiles profiles &rest body

All connection-local variables, which are specified by a connection profile in profiles, are applied.

After that, body is executed, and the connection-local variables are unwound. Example:

(connection-local-set-profile-variables
  'remote-perl
  '((perl-command-name . "/usr/local/bin/perl")
    (perl-command-switch . "-e %s")))

(with-connection-local-profiles '(remote-perl)
  do something useful)

Variable: enable-connection-local-variables: If nil, connection-local variables are ignored. This variable shall be changed temporarily only in special modes.

12.15 変数のエイリアス

シノニムとして2つの変数を作成できれば便利なときがあります。2つの変数は常に同じ値をもち、どちらか一方を変更すると、もう一方も変更されます。変数の名前を変更 — 古い名前はよく考慮して選択されたものではなかったとか、変数の意味が部分的に変更された等の理由で — するとき、互換性のために新しい名前のエイリアス(alias)として古い名前を維持できれば便利なときがあるかもしれません。defvaraliasによってこれを行うことができます。

Function: defvaralias new-alias base-variable &optional docstring

この関数はシンボルbase-variableのエイリアスとして、シンボルnew-aliasを定義する。これはnew-aliasから値を取得するとbase-variableの値がリターンされ、new-aliasの値を変更するとbase-variableの値が変更されることを意味する。エイリアスされた2つの変数名は、常に同じ値と同じバインディングを共有する。

docstring引数が非nilなら、それはnew-aliasのドキュメント文字列を指定する。それ以外なら、エイリアスは(もしあれば)base-variableと同じドキュメント文字列となる。ただしそれはbase-variable自体がエイリアスではない場合で、エイリアスならnew-aliasはエイリアスチェーンの最後の変数のドキュメント文字列になる。

この関数はbase-variableをリターンする。

変数のエイリアスは、変数にたいする古い名前を新しい名前に置き換える便利な方法です。make-obsolete-variableは古い名前を陳腐化(obsolete)していると宣言して。それが将来のある時点で削除されるかもしれないことを宣言します。

Function: make-obsolete-variable obsolete-name current-name when &optional access-type

この関数はバイトコンパイラーに変数obsolete-nameが陳腐化していると警告させる。current-nameがシンボルなら、それはこの変数の新たな名前である。警告メッセージはその後、obsolete-nameのかわりにcurrent-nameを使用するよう告げるようになる。current-nameが文字列なら、それはメッセージであり、置き換えられる変数はない。whenはその変数が最初に陳腐化するのがいつかを示す文字列(通常はバージョン番号文字列)。

オプションの引数access-typeが非nilなら、それは陳腐化の警告を引き起こすアクセスの種類を指定すること。getかsetを指定できる。

2つの変数シノニムを作成してマクロdefine-obsolete-variable-aliasを使用することにより、1つが陳腐化していると同時に宣言できます。

Macro: define-obsolete-variable-alias obsolete-name current-name &optional when docstring

このマクロは変数obsolete-nameが陳腐化しているとマークして、それを変数current-nameにたいするエイリアスにする。これは以下と等価である:

(defvaralias obsolete-name current-name docstring)
(make-obsolete-variable obsolete-name current-name when)

Function: indirect-variable variable

この関数はvariableのエイリアスチェーンの最後の変数をリターンする。variableがシンボルでない、またはvariableがエイリアスとして定義されていなければ、この関数はvariableをリターンする。

この関数はシンボルのチェーンがループしていたら、cyclic-variable-indirectionエラーをシグナルする。

(defvaralias 'foo 'bar)
(indirect-variable 'foo)
     ⇒ bar
(indirect-variable 'bar)
     ⇒ bar
(setq bar 2)
bar
     ⇒ 2

foo
     ⇒ 2

(setq foo 0)
bar
     ⇒ 0
foo
     ⇒ 0

12.16 値を制限された変数

通常のLisp変数には、有効なLispオブジェクトである任意の値を割り当てることができます。しかしLispではなくCで定義されたLisp変数もあります。これらの変数のほとんどは、DEFVAR_LISPを使用してCコードで定義されています。Lispで定義された変数と同様、これらは任意の値をとることができます。しかしいくつかの変数はDEFVAR_INTやDEFVAR_BOOLを使用して定義されています。C実装の概要的な議論は、Writing Emacs Primitives、特にsyms_of_filename型の関数の説明を参照してください。

DEFVAR_BOOL型の変数は、値にnilかtしかとることができません。他の値の割り当てを試みるとtがセットされます:

(let ((display-hourglass 5))
  display-hourglass)
     ⇒ t

Variable: byte-boolean-vars: この変数はDEFVAR_BOOL型のすべての変数のリストを保持する。

DEFVAR_INT型の変数は、整数値だけをとることができます。他の値の割り当てを試みると結果はエラーになります:

(setq undo-limit 1000.0)
error→ Wrong type argument: integerp, 1000.0

12.17 ジェネリック変数

A generalized variable or place form is one of the many places in Lisp memory where values can be stored using the setf macro (see section setfマクロ). The simplest place form is a regular Lisp variable. But the CARs and CDRs of lists, elements of arrays, properties of symbols, and many other locations are also places where Lisp values get stored.

ジェネリック変数は、C言語のlvalues(左辺値)と類似しています。C言語のlvalueでは‘x = a[i]’で配列から要素を取得し、同じ表記を使用して‘a[i] = x’で要素を格納します。Cではa[i]のような特定のフォームがlvalueになれるように、Lispでジェネリック変数になることができる一連のフォームが存在します。

12.17.1 `setf`マクロ

The setf macro is the most basic way to operate on generalized variables. The setf form is like setq, except that it accepts arbitrary place forms on the left side rather than just symbols. For example, (setf (car a) b) sets the car of a to b, doing the same operation as (setcar a b), but without you having to use two separate functions for setting and accessing this type of place.

Macro: setf [place form]…: このマクロはformを評価して、それをplaceに格納する。placeは有効なジェネリック変数フォームでなければならない。複数のplace/formペアーがある場合、割り当てはsetqの場合と同様。setfは最後のformの値をリターンする。

The following Lisp forms are the forms in Emacs that will work as generalized variables, and so may appear in the place argument of setf:

A symbol. In other words, (setf x y) is exactly equivalent to (setq x y), and setq itself is strictly speaking redundant given that setf exists. Most programmers will continue to prefer setq for setting simple variables, though, for stylistic and historical reasons. The macro (setf x y) actually expands to (setq x y), so there is no performance penalty for using it in compiled code.

以下の標準的なLisp関数の呼び出し:

aref      cddr      symbol-function
car       elt       symbol-plist
caar      get       symbol-value
cadr      gethash
cdr       nth
cdar      nthcdr

以下のEmacs特有な関数の呼び出し:

alist-get                     process-get
frame-parameter               process-sentinel
terminal-parameter            window-buffer
keymap-parent                 window-display-table
match-data                    window-dedicated-p
overlay-get                   window-hscroll
overlay-start                 window-parameter
overlay-end                   window-point
process-buffer                window-start
process-filter                default-value

どのように処理すれば良いか未知なplaceフォームを渡すと、setfはエラーをシグナルします。

nthcdrの場合、関数のリスト引数はそれ自体が有効なplaceフォームでなければならないことに注意してください。たとえば(setf (nthcdr 0 foo) 7)は、foo自体に7をセットするでしょう。

マクロpush(リスト変数の変更を参照)とpop(リスト要素へのアクセスを参照)は、リストだけでなくジェネリック変数を操作できます。(pop place)はplace内に格納されたリストの最初の要素を削除してリターンします。これは(prog1 (car place) (setf place (cdr place)))と似ていますが、すべてのサブフォームを一度だけ評価します。(push x place)はplace内に格納されたリストの1番前にxを挿入します。これは(setf place (cons x place))と似ていますが、サブフォームの評価が異なります。nthcdr placeへのpushとpopは、リスト内の任意の位置での挿入ち削除に使用できることに注意してください。

cl-libライブラリーでは追加のsetf placeを含む、ジェネリック変数にたいするさまざまな拡張が定義されています。Generalized Variables in Common Lisp Extensionsを参照してください。

12.17.2 新たな`setf`フォーム

このセクションでは、setfが操作できる新たなフォームの定義方法を説明します。

Macro: gv-define-simple-setter name setter &optional fix-return

このマクロは単純なケースでsetfメソッドを簡単に定義することを可能にする。nameは関数、マクロ、スペシャルフォームの名前。nameがそれを更新するための対応するsetter関数をもつなら、このマクロを使用できる(たとえば(gv-define-simple-setter car setcar))。

このマクロは以下のフォームの呼び出しを

(setf (name args…) value)

以下のように変換する。

(setter args… value)

このようなsetfの呼び出しはvalueをリターンするとドキュメントされている。これはcarとsetcarでは問題はない。setcarはそれがセットする値をリターンするからである。setter関数がvalueをリターンしない場合には、gv-define-simple-setterのfix-return引数に、非nil値を使用すること。これは以下のようなものに展開される

(let ((temp value))
  (setter args… temp)
  temp)

これで正しい結果がリターンされることが保証される。

Macro: gv-define-setter name arglist &rest body

このマクロは上述のフォームより複雑なsetf展開を可能にする。たとえば呼び出すべきシンプルなsetter関数が存在しないときや、もしそれが存在してもplaceフォームとは異なる引数を要求するなら、このフォームを使う必要があるかもしれない。

このマクロは最初にsetf引数フォーム(value args…)をarglistにバインドして、その後bodyを実行することによって、フォーム(setf (name args…) value)を展開する。bodyは割り当てを行うLispフォームをリターンして、最終的にはセットされた値をリターンすること。以下はこのマクロの使用例である:

(gv-define-setter caar (val x) `(setcar (car ,x) ,val))

展開をさらに制御するならマクロgv-define-expanderを参照してください。マクロgv-letplaceはsetfのような処理を行うマクロを定義するのに有用です。詳細はgv.elのソースファイルを参照してください。

Common Lispに関する注意: Common Lispは関数としてのsetf、すなわち関数名がシンボルではなくリスト(setf name)であるようなsetf関数の挙動を指定するために別の方法を定義する。たとえば(defun (setf foo) …)は、setfがfooに適用されるときに使用される関数を定義する。Emacsはこれをサポートしない。適切な展開が定義されていないフォームにsetfを使用するとコンパイル時エラーとなる。Common Lispでは後で関数(setf func)が定義されるのでエラーにならない。

13 関数

Lispプログラムは主にLisp関数で構成されます。このチャプターはで関数とは何か、引数を受け取る方法、そして関数を定義する方法を説明します。

13.1 関数とは?		Lisp関数 vs. プリミティブ。専門用語。
13.2 ラムダ式		関数がLispオブジェクトとして表現される方法。
13.3 関数の命名		シンボルは関数を命名できる。
13.4 関数の定義		関数定義のためのLisp式。
13.5 関数の呼び出し		既存の関数を使う方法。
13.6 関数のマッピング		リストの各要素などに関数を適用する。
13.7 無名関数		ラムダ式、それは無名の関数。
13.8 Generic Functions		Polymorphism, Emacs-style.
13.9 関数セルの内容へのアクセス		シンボルの関数定義へのアクセスとセット。
13.10 クロージャー		レキシカル環境に囲まれた関数。
13.11 Emacs Lisp関数にたいするアドバイス		関数の定義への追加。
13.12 関数を陳腐と宣言する
13.13 インライン関数Inline Functions		コンパイラーによりインライン展開される関数。
13.14 `declare`フォーム		関数についての補足的な情報の追加。
13.15 コンパイラーへの定義済み関数の指示		関数が定義されていることをコンパイラーに知らせる。
13.16 安全に関数を呼び出せるかどうかの判断		呼び出しても安全な関数なのか判断する。
13.17 関数に関するその他トピック		関数が動作する方法において特別な意味をもつ、特定のLispプリミティブのクロスリファレンス。

13.1 関数とは?

一般的な意味において関数とは、引数(arguments)と呼ばれる与えられた入力値の計算を担うルールです。計算の結果はその関数の値(value)、またはリターン値(return value)と呼ばれます。計算では変数の値やデータ構造の内容を変更する等の副作用をもつこともできます。

ほとんどのコンピューター言語では、関数はそれぞれ名前をもちます。しかしLispでは厳密な意味において関数は名前をもちません。関数はオブジェクトであり、関数の名前の役割を果たすシンボルに関連づけることができますが(たとえばcar)、それはオプションです。関数の命名を参照してください。関数が名前を与えられたとき、通常はそのシンボルを“関数”として参照します(たとえば関数carのように参照する)。このマニュアルでは、関数名と関数オブジェクト自身との間の区別は通常は重要ではありませんが、それが意味をもつような場合には注記します。

スペシャルフォーム(special form)、マクロ(macro)と呼ばれる関数likeなオブジェクトがいくつかあり、それらも引数を受け取って計算を行います。しかし以下で説明するようにEmacs Lispではこれらは関数とはみなされません。

以下は関数と関数likeなオブジェクトにたいする重要な条件です:

lambda expression

Lispで記述された関数(厳密には関数オブジェクト)。これらについては以降のセクションで説明します。ラムダ式を参照のこと。

primitive

Lispから呼び出すことができるが実際にはCで記述されている。プリミティブはビルトイン関数(built-in functions)とかサブルーチン(subr)のようにも呼ばれる。それらの例には関数likeなcarやappendが含まれる。加えてすべてのスペシャルフォーム(以下参照)もプリミティブとみなされる。

関数はLispの基礎となる部分(たとえばcar)であり、オペレーティングシステムのサービスにたいして低レベルのインターフェースを与え、高速に実行される必要があるために、通常はプリミティブとして実装されている。Lispで定義された関数と異なり、プリミティブの修正や追加には、Cソースの変更とEmacsのリコンパイルが必要となる。Emacsプリミティブの記述を参照のこと。

special form

プリミティブは関数と似ているが、すべての引数が通常の方法で評価されない。いくつかの引数だけが評価されるかもしれず、通常ではない順序で評価されるか、複数回評価されるかもしれない。プリミティブの例にはif、and、whileが含まれる。スペシャルフォームを参照のこと。

macro

あるLisp式をオリジナルの式のかわりに評価される別の式に変換する、関数とは別のLispで定義された構文。マクロはスペシャルフォームが行う一連のことを、Lispプログラマーが行うのを可能にする。マクロを参照のこと。

command

プリミティブcommand-executeを通じて呼び出すことができるオブジェクトで、通常はそのコマンドにバインドされたキーシーケンスをユーザーがタイプすることにより呼び出される。interactiveな呼び出しを参照のこと。コマンドは通常は関数である。その関数がLispで記述されていれば、関数の定義内のinteractiveフォームによってコマンドとなる(コマンドの定義を参照)。関数であるコマンドは他の関数と同様、Lisp式から呼び出すこともできる。

キーボードマクロ(文字列かベクター)は関数ではないが、これらもコマンドである。キーボードマクロを参照のこと。シンボルの関数セルにコマンドが含まれてれば、わたしたちはそのシンボルをコマンドと言う(シンボルの構成要素を参照)。そのような名前つきコマンド(named command)はM-xで呼び出すことができる。

closure

ラムダ式とよく似た関数オブジェクトだが、クロージャーはレキシカル変数バインディングの環境にも囲われている。クロージャーを参照のこと。

byte-code function

バイトコンパイラーによりコンパイル済みの関数。バイトコード関数型を参照のこと。

autoload object

実際の関数のプレースホルダー。autoloadオブジェクトが呼び出されると、Emacsは実際の関数の定義を含むファイルをロードした後に実際の関数を呼び出す。autoloadを参照のこと。

関数functionpを使用して、あるオブジェクトが関数かどうかテストできます:

Function: functionp object: この関数はobjectが任意の種類の関数(funcallに渡すことができる)ならtをリターンする。functionpは関数を名づけるシンボルにたいしてはt、スペシャルフォームにたいしてはnilをリターンすることに注意。

It is also possible to find out how many arguments an arbitrary function expects:

Function: func-arity function

This function provides information about the argument list of the specified function. The returned value is a cons cell of the form (min . max), where min is the minimum number of arguments, and max is either the maximum number of arguments, or the symbol many for functions with &rest arguments, or the symbol unevalled if function is a special form.

Note that this function might return inaccurate results in some situations, such as the following:

- Functions defined using apply-partially (see section apply-partially).
- Functions that are advised using advice-add (see section 名前つき関数にたいするアドバイス).
- Functions that determine the argument list dynamically, as part of their code.

functionpと異なり、以下の3つの関数はシンボルをそれの関数定義としては扱いません。

Function: subrp object

この関数はobjectがビルトイン関数(たとえばLispプリミティブ)ならtをリターンする。

(subrp 'message)            ; messageはシンボルであり、
     ⇒ nil                 ;   subrオブジェクトではない

(subrp (symbol-function 'message))
     ⇒ t

Function: byte-code-function-p object

この関数はobjectがバイトコード関数ならtをリターンする。たとえば:

(byte-code-function-p (symbol-function 'next-line))
     ⇒ t

Function: subr-arity subr: This works like func-arity, but only for built-in functions and without symbol indirection. It signals an error for non-built-in functions. We recommend to use func-arity instead.

13.2 ラムダ式

ラムダ式(lambda expression)はLispで記述された関数オブジェクトです。以下は例です:

(lambda (x)
  "Xの双曲線コサインをreturnする"
  (* 0.5 (+ (exp x) (exp (- x)))))

Emacs Lispではこのようなリストは、関数オブジェクトに評価される有効な式です。

ラムダ式自身は名前をもたない無名関数(anonymous function)です。ラムダ式をこの方法で使用できますが(無名関数を参照)、名前付き関数(named functions)を作成するためにシンボルに関連付けられる方が一般的です(関数の命名を参照)。これらの詳細に触れる前に以下のサブセクションではラムダ式の構成要素と、それらが行うことについて説明します。

13.2.1 ラムダ式の構成要素

ラムダ式は以下のようなリストです:

(lambda (arg-variables…)
  [documentation-string]
  [interactive-declaration]
  body-forms…)

ラムダ式の1番目の要素は常にシンボルlambdaです。これはそのリストが関数を表すことを示します。lambdaで関数定義を開始する理由は、別の目的での使用が意図された他のリストが、意図せずに関数として評価されないようにするためです。

2番目の要素はシンボル — 引数変数名のリストです。これはラムダリスト(lambda list)と呼ばれます。Lisp関数が呼び出されたとき、引数値はラムダリスト内の変数と対応付けされます。ラムダリストには、与えられた値にたいするローカルバインディングが付与されます。ローカル変数を参照してください。

ドキュメント文字列(documentation string)はEmacs Lispのヘルプ機能にたいして、その関数を説明する関数定義に配されたLispの文字列オブジェクトです。関数のドキュメント文字列を参照してください。

インタラクティブ宣言(interactive declaration)は、(interactive code-string)という形式のリストです。これはこの関数が対話的に使用された場合に引数を提供する方法を宣言します。この宣言をもつ関数は、コマンド(command)と呼ばれます。コマンドはM-xを使用したり、キーにバインドして呼び出すことができます。この方法で呼び出されることを意図しない関数は、インタラクティブ宣言を持つべきではありません。インタラクティブ定義を記述する方法は、コマンドの定義を参照してください。

残りの要素はその関数のbody(本体) — その関数が処理を行うためのLispコード(Lispプログラマーは“評価されるLispフォームのリスト”と言うだろう)です。この関数からリターンされる値は、bodyの最後の要素によりリターンされる値です。

13.2.2 単純なラムダ式の例

以下の例を考えてみてください:

(lambda (a b c) (+ a b c))

以下のようにfuncallに渡すことにより、この関数を呼び出すことができます:

(funcall (lambda (a b c) (+ a b c))
         1 2 3)

この呼び出しは変数aに1、bに2、cに3をバインドして、ラムダ式のbodyを評価します。bodyの評価によってこれら3つの数が加算されて、6が結果として生成されます。したがってこの関数呼び出しにより6がリターンされます。

以下のように引数は他の関数の結果であってもよいことに注意してください:

(funcall (lambda (a b c) (+ a b c))
         1 (* 2 3) (- 5 4))

これは引数1、(* 2 3)、(- 5 4)を左から右に評価します。その後ラムダ式に引数1、6、1を適用して値8が生成されます。

これらの例が示すように、ローカル変数を作成してそれらに値を与えるフォームとして、CARがラムダ式であるようなフォームを使用することができます。古い時代のLispでは、この方法がローカル変数をバインドして初期化する唯一の方法でした。しかし現在ではこの目的にはフォームletを使用するほうが明解です(ローカル変数を参照)。ラムダ式は主に他の関数の引数として渡される無名関数(無名関数を参照)として、あるいは名前つき関数(関数の命名を参照)を生成するためにシンボルの関数定義に格納するために使用されます。

13.2.3 引数リストのその他機能

Our simple sample function, (lambda (a b c) (+ a b c)), specifies three argument variables, so it must be called with three arguments: if you try to call it with only two arguments or four arguments, you get a wrong-number-of-arguments error (see section エラー).

特定の引数を省略できる関数を記述できると便利なこともあります。たとえば関数substringは3つの引数 — 文字列、開始インデックス、終了インデックス — を受け取りますが、3つ目の引数を省略すると、デフォルトでその文字列のlengthとなります。関数listや+が行うように、特定の関数にたいして不定個の引数を指定できると便利なときもあります。

関数が呼び出されるとき省略されるかもしれないオプションの引数を指定するには、オプションの引数の前にキーワード&optionalを含めるだけです。0個以上の追加引数のリストを指定するには、最後の引数の前にキーワード&restを含めます。

したがって引数リストの完全な構文は以下のようになります:

(required-vars…
 [&optional optional-vars…]
 [&rest rest-var])

角カッコ(square bracket)は&optionalと&rest、およびそれらに続く変数が省略できることを示します。

この関数の呼び出しではrequired-varsのそれぞれにたいして、実際の引数が要求されます。0個以上のoptional-varsにたいして実際の引数があるかもしれませんが、ラムダ式が&restを使用していなければ、その個数を超えて実際の引数を記述することはできません。&restが記述されていれば、追加で任意の個数の実際の引数があるかもしれません。

optionaやrest変数にたいして実際の引数が省略されると、それらのデフォルトは常にnilになります。関数にたいして引数に明示的にnilが使用されたのか、引数が省略されたのかを区別することはできません。しかし関数のbodyが、nilを他の有意な値が省略されたと判断することは自由です。substringはこれを行います。substringの3つ目の引数がnilなら、それは文字列の長さを使用することを意味します。

Common Lispに関する注意: Common Lispではオプションの引数が省略されたときに使用するデフォルト値を指定できる。Emacs Lispでは、引数が明示的に渡されたかを調べるsupplied-p変数はサポートされない。

例えば引数リストは以下のようになります:

(a b &optional c d &rest e)

aとbは最初の2つの実引数となり、これらは必須です。さらに1つまたは2つの引数が指定された場合、それらは順番にcとdにバインドされます。1つ目から4つ目の引数の後の引数は、リストにまとめられてeにそのリストがバインドされます。2つしか引数が指定されなかったら、cはnilになります。2つか3つの引数なら、dはnilです。引数が4つ以下なら、eはnilになります。

オプションの引数の後ろに必須の引数を指定する方法はありません — これは意味を成さないからです。なぜそうなるかは、この例でcがオプションでdが必須な場合を考えてみてください。実際に3つの引数が与えられたとします。3番めの引数は何を指定したのでしょうか? この引数はcなのでしょうか、それともdに使用されるのでしょうか? 両方の場合が考えられます。同様に&rest引数の後に、さらに引数(必須またはオプション)をもつことも意味を成しません。

以下に引数リストと、それを正しく呼び出す例をいくつか示します:

(funcall (lambda (n) (1+ n))        ; 1つの必須:
         1)                         ; これは正確に1つの引数を要求する
     ⇒ 2
(funcall (lambda (n &optional n1)   ; 1つは必須で、1つはオプション:
           (if n1 (+ n n1) (1+ n))) ; 1つまたは2つの引数
         1 2)
     ⇒ 3
(funcall (lambda (n &rest ns)       ; 1つは必須で、後は残り:
           (+ n (apply '+ ns)))     ; 1つ以上の引数
         1 2 3 4 5)
     ⇒ 15

13.2.4 関数のドキュメント文字列

ラムダ式はラムダリストの直後に、オプションでドキュメント文字列(documentation string)をもつことができます。この文字列は、その関数の実行に影響を与えません。これはコメントの一種ですがLisp機構に内在するシステム化されたコメントであり。Emacsのヘルプ機能で使用できます。ドキュメント文字列にアクセスする方法は、ドキュメントを参照してください。

たとえその関数があなたのプログラム内だけで呼び出される関数だとしても、すべての関数にドキュメント文字列を与えるのはよいアイデアです。ドキュメント文字列はコメントと似ていますが、コメントより簡単にアクセスできます。

ドキュメント文字列の1行目は、関数自体にもとづくものであるべきです。なぜならaproposは、最初の1行目だけを表示するからです。ドキュメント文字列の1行目は、その関数の目的を要約する1つか2つの完全なセンテンスで構成されるべきです。

ドキュメント文字列の開始は通常、ソースファイル内ではインデントされていますが、ドキュメント文字列の開始のダブルクォート文字の前にインデントのスペースがあるので、インデントはドキュメント文字列の一部にはなりません。ドキュメント文字列の残りの行がプログラムソース内で揃うようにインデントする人がいます。これは間違いです。後続の行のインデントは文字列の内部にあります。これはソースコード内での見栄えはよくなりますが、ヘルプコマンドで表示したとき見栄えが悪くなります。

ドキュメント文字列がなぜオプションになるのか不思議に思うかもしれません。なぜならドキュメント文字列の後には必須となる関数の構成要素であるbodyが続くからです。文字列を評価するとその文字列自身がリターンされるので、それがbody内の最後のフォームでない限りなんの効果もありません。したがって実際はbodyの1行目とドキュメント文字列で混乱が生じることはありません。bodyの唯一のフォームが文字列なら、それはリターン値とドキュメントの両方の役目を果たします。

ドキュメント文字列の最後の行には、実際の関数引数とは異なる呼び出し規約を指定できます。これは以下のようなテキストを記述します

\(fn arglist)

そのテキストの後に空行を配置して、テキスト自身は行頭から記述、ドキュメント文字列内でこのテキストの後に改行が続かないように記述します(‘\’はEmacsの移動コマンドが混乱するのを避けるために使用する)。この方法で指定された呼び出し規約は、ヘルプメッセージ内で関数の実引数から生成される呼び出し例と同じ場所に表示されます。

マクロ定義内に記述された引数は、ユーザーがマクロ呼び出しの一部だと考える方法とは合致しない場合がしばしばあるので、この機能はマクロ定義で特に有用です。

Do not use this feature if you want to deprecate the calling convention and favor the one you advertise by the above specification. Instead, use the advertised-calling-convention declaration (see section declareフォーム) or set-advertised-calling-convention (see section 関数を陳腐と宣言する), because these two will cause the byte compiler emit a warning message when it compiles Lisp programs which use the deprecated calling convention.

13.3 関数の命名

シンボルは関数の名前となることができます。これはそのシンボルの関数セル(function cell: シンボルの構成要素を参照)が、関数オブジェクト(たとえばラムダ式)を含むときに起こります。するとそのシンボル自身が呼び出し可能な有効な関数、つまりそのシンボルの関数セルの関数と等価になります。

関数セルの内容はそのシンボルの関数定義(function definition)と呼ぶこともできます。そのシンボルのかわりにシンボルの関数定義を使う手続きのことをシンボル関数インダイレクション(symbol function indirection)と呼びます。シンボル関数インダイレクションを参照。与えられたシンボルに関数定義がなければシンボルの関数セルはvoidと呼ばれ、それを関数として使用することはできません。

実際のところほとんどすべての関数は名前をもち、その名前により参照されます。ラムダ式を定義することで名前つきのLisp関数を作成、それを関数セル(関数セルの内容へのアクセスを参照)に置くことができます。しかしより一般的なのはdefunスペシャルフォーム(次のセクションで説明)を使う方法です。関数の定義を参照してください。

わたしたちが関数に名前を与えるのは、Lisp式内で関数を名前で参照するのが便利だからです。また名前つきの関数は簡単に自分自身を — 再帰的(recursive)に参照することができます。さらにプリミティブはテキスト的な名前だけで参照することができます。なぜならプリミティブ関数は入力構文(read syntax)をもたないオブジェクトだからです(プリミティブ関数型を参照)。

関数が一意な名前をもつ必要はありません。与えられた関数オブジェクトは通常は1つのシンボルの関数セルだけに存在しますが、これは単に慣習的なものです。fsetを使用すれば関数を複数のシンボルに格納するのは簡単です。それらのシンボルはそれぞれ、同じ関数にたいする有効な名前となります。

関数として使用しているシンボルを、変数としても利用できることに注意してください。シンボルのこれら2つの利用法は独立しており、競合はしません(これはSchemaのような他のいくつかのLisp方言には当てはまらない)。

By convention, if a function’s symbol consists of two names separated by ‘--’, the function is intended for internal use and the first part names the file defining the function. For example, a function named vc-git--rev-parse is an internal function defined in vc-git.el. Internal-use functions written in C have names ending in ‘-internal’, e.g., bury-buffer-internal. Emacs code contributed before 2018 may follow other internal-use naming conventions, which are being phased out.

13.4 関数の定義

わたしたちは通常は関数を最初に作成したときに名前を与えます。これは関数の定義(defining a function)と呼ばれ、defunマクロにより行われます。

Macro: defun name args [doc] [declare] [interactive] body…

defunは新たなLisp関数を定義する通常の方法である。これは引数リストargs、およびbodyにより与えられるbodyフォームとともに、シンボルnameを関数として定義する。nameとargsをクォートする必要はない。

docが与えられたら、それはその関数のドキュメント文字列を指定する文字列であること(関数のドキュメント文字列を参照)。declareが与えられたら、それは関数のメタデータを指定するdeclareフォームであること(declareフォームを参照)。interactiveが与えられたら、それは関数が対話的に呼び出される方法を指定するinteractiveフォームであるこ(interactiveな呼び出しを参照)。

defunのリターン値は定義されていません。

以下にいくつか例を示す:

(defun foo () 5)
(foo)
     ⇒ 5

(defun bar (a &optional b &rest c)
    (list a b c))
(bar 1 2 3 4 5)
     ⇒ (1 2 (3 4 5))

(bar 1)
     ⇒ (1 nil nil)

(bar)
error→ Wrong number of arguments.

(defun capitalize-backwards ()
  "Upcase the last letter of the word at point."
  (interactive)
  (backward-word 1)
  (forward-word 1)
  (backward-char 1)
  (capitalize-word 1))

意図せず既存の関数を再定義しないように注意されたい。defunはcarのようなプリミティブ関数でさえ、問い合わせせずに躊躇なく再定義する。Emacsがこれを妨げることはない。なぜなら関数の再定義は故意に行われることがあり、そのような意図した再定義を、意図しない再定義と見分ける方法はがないからである。

Function: defalias name definition &optional doc

この関数は定義definition(任意の有効なLisp関数)とともに、シンボルnameを関数として定義する。この関数のリターン値は未定義。

docが非nilなら、それは関数nameのドキュメントとなる。それ以外ならdefinitionにより提供されるドキュメントが使用される。

内部的にはdefaliasは、通常は定義のセットにfsetを使用する。しかしnameがdefalias-fset-functionプロパティーをもつなら、fsetを呼び出すかわりにそれに割り当てられた値を使用する。

defaliasを使う正しい場所は、特定の関数名が正に定義される場所 — 特にソースファイルがロードされるとき明示的にその名前が出現する場所である。これはdefaliasがdefunと同じように、どれが関数を定義するファイルなのか記録するからである(アンロードを参照)。

それとは対象的に他の目的のために関数を操作するプログラムでは、そのような記録を保持しないfsetを使用するほうがよいだろう。関数セルの内容へのアクセスを参照のこと。

defunやdefaliasで新たなプリミティブ関数を作成することはできませんが、任意の関数定義を変更するのに使用することができ、通常の定義がプリミティブであるcarやx-popup-menuのような関数でさえ変更することができます。しかしこれは危険なことです。たとえばLispの完全性を損なうことなく、carを再定義するのはほとんど不可能だからです。それほど有名ではないx-popup-menuのような関数の再定義では、危険は減少しますが、それでも期待したとおりに機能しないかもしれません。Cコードにそのプリミティブの呼び出しがあれば、それは直接そのプリミティブのC定義を呼び出すので、シンボル定義を変更してもそれらに影響はありません。

defsubstも参照してください。これはdefunのように関数を定義して、それのインライン展開を処理するようLispコンパイラーに指示します。インライン関数Inline Functionsを参照してください。

かわりにコンパイラーマクロとしてインライン展開されるコードを記述することにより関数を定義できます。以下のマクロがこれを可能にします。

Macro: define-inline name args [doc] [declare] body…

自身をインライン化するコードを提供することにより、コンパイラーマクロとして関数nameを定義する。この関数は引数リストargsを受け取り、指定されたbodyをもつ。

docが与えられたなら、それは関数のドキュメント文字列であること(関数のドキュメント文字列を参照)。declareが与えられたなら、それは関数のメタデータを指定するdeclareフォームであること(declareフォームを参照)。

define-inlineで定義された関数は、defsubstやdefmacroで定義されたマクロにたいして複数の利点をもちます。

- mapcarに渡すことができる(関数のマッピングを参照)。
- より効率的である。
- 値を格納するためのplaceフォーム(place forms)として使用できる(ジェネリック変数を参照)。
- cl-defsubstより予測可能な方法で振る舞う(Argument Lists in Common Lisp Extensions for GNU Emacs Lispを参照)。

defmacroと同様に、define-inlineでインライン化された関数は、呼び出し側からダイナミックかレキシカルいずれかのスコーピングルールを継承します。変数のバインディングのスコーピングルールを参照してください。

以下のマクロはdefine-inlineで定義された関数のbody内で使用する必要があります。

Macro: inline-quote expression: define-inlineにたいしてexpressionをクォートする。これはバッククォート(バッククォートを参照)と似ているが、コードをクォートして,だけを受け入れ、,@は受け入れない。

Macro: inline-letevals (bindings…) body…: This is similar to let (see section ローカル変数): it sets up local variables as specified by bindings, and then evaluates body with those bindings in effect. Each element of bindings should be either a symbol or a list of the form (var expr); the result is to evaluate expr and bind var to the result. The tail of bindings can be either nil or a symbol which should hold a list of arguments, in which case each argument is evaluated, and the symbol is bound to the resulting list.

Macro: inline-const-p expression: expressionの値が既知なら非nilをリターンする。

Macro: inline-const-val expression: expressionの値をリターンする。

Macro: inline-error format &rest args: formatに応じてargsをフォーマットしてエラーをシグナルする。

以下はdefine-inlineを使用した例です:

(define-inline myaccessor (obj)
  (inline-letevals (obj)
    (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2)))))

これは以下と等価です

(defsubst myaccessor (obj)
  (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2)))

13.5 関数の呼び出し

関数を定義しただけでは半分しか終わっていません。関数はそれを呼び出す(call) — たとえば実行(run)するまでは何も行いません。関数のcallはinvocationとしても知られています。

関数を呼び出すもっとも一般的な方法は、リストの評価によるものです。たとえばリスト(concat "a" "b")を評価することにより、関数concatが引数"a"と"b"で呼び出されます。評価については評価を参照してください。

プログラム内で式としてリストを記述するときは、プログラム内にテキストでどの関数を呼び出すか、いくつの引数を与えるかを指定します。通常はこれが行いたいことです。どの関数を呼び出すかを実行時に計算する必要がある場合もあります。これを行うには関数funcallを使用します。実行時にいくつの引数を渡すか決定する必要があるときはapplyを使用します。

Function: funcall function &rest arguments

funcallは関数functionを引数argumentsで呼び出して、functionがリターンした値をリターンする。

funcallは関数なので、functionを含むすべての引数はfuncallの呼び出し前に評価される。これは呼び出される関数を得るために任意の式を使用できることを意味している。またfuncallがargumentsに記述した式ではなく、その値だけを見ることを意味している。これらの値はfunction呼び出し中では、2回目は評価されない。funcallの処理は関数の通常の呼び出し手続きと似ており、すでに評価された引数は評価されない。

引数functionはLisp関数かプリミティブ関数でなければならない。つまりスペシャルフォームやマクロは、未評価の引数式を与えられたときだけ意味があるので、指定することはできない。上述したように最初の場所でfuncallがそれらを知らないので、funcallがそれらを提供することはできない。

コマンドの呼び出しにfuncallを使用して、それがインタラクティブに呼び出されたように振る舞うようにする必要があるなら、funcall-interactivelyを使用すること(interactiveな呼び出しを参照)。

(setq f 'list)
     ⇒ list

(funcall f 'x 'y 'z)
     ⇒ (x y z)

(funcall f 'x 'y '(z))
     ⇒ (x y (z))

(funcall 'and t nil)
error→ Invalid function: #<subr and>

これらの例をapplyの例と比較されたい。

Function: apply function &rest arguments

applyは関数functionを引数argumentsで呼び出す。これはfuncallと同様だが1つ違いがある。argumentsの最後はオブジェクトのリストである。これは1つのリストではなく、個別の引数としてfunctionに渡される。わたしたちはこれを、applyがこのリストを展開(spread)(個々の要素が引数となるので)すると言う。

applyはfunctionを呼び出した結果をリターンする。funcallと同様、functionはLisp関数かプリミティブ関数でなければならない。つまりスペシャルフォームやマクロはapplyでは意味をもたない。

(setq f 'list)
     ⇒ list

(apply f 'x 'y 'z)
error→ Wrong type argument: listp, z

(apply '+ 1 2 '(3 4))
     ⇒ 10

(apply '+ '(1 2 3 4))
     ⇒ 10

(apply 'append '((a b c) nil (x y z) nil))
     ⇒ (a b c x y z)

applyを使用した興味深い例はDefinition of mapcarを参照のこと。

ある関数にたいして、その関数のある引数を特定の値に固定して、他の引数は実際に呼びだされたときの値にできれば便利なことがあります。関数のいくつかの引数を固定することは、その関数の部分適用(partial application)と呼ばれます⁹。これの結果は残りの引数をとる新たな関数で、すべての引数を合わせて元の関数を呼び出します。

Emacs Lispで部分適用を行う方法を示します:

Function: apply-partially func &rest args

この関数は新たな関数をリターンする。この新しい関数は呼びだされたときにargs、および呼び出し時に指定された追加の引数から成る引数リストでfuncを呼び出す関数である。funcにn個の引数を指定できる場合、m < n個の引数でapply-partiallyを呼び出すと、n - m個の新たな関数を生成する。

以下はビルトイン関数1+が存在しないものとして、apply-partiallyと他のビルトイン関数+を使用して1+を定義する例である:

(defalias '1+ (apply-partially '+ 1)
  "Increment argument by one.")

(1+ 10)
     ⇒ 11

引数として関数を受け取ったり、データ構造(特にフック変数やプロパティーリスト)から関数を探す関数はLispでは一般的で、それらはfuncallやapplyを使用してそれらの関数を呼び出します。引数として関数をとる関数は、ファンクショナル(functional)と呼ばれるときもあります。

ファンクショナルを呼び出すとき、引数としてno-op関数(何も行わない関数)を指定できると便利なときがあります。以下に２つの異なるno-op関数を示します:

Function: identity arg: この関数はargをリターンする。副作用はない。

Function: ignore &rest args: この関数はすべての引数を無視してnilをリターンする。

関数のいくつかはユーザーに可視なコマンドで、これらは(通常はキーシーケンスを介して)対話的に呼び出すことができます。そのようなコマンドは、call-interactively関数を使用することにより、対話的に呼びだされたときと同様に呼び出すことができます。interactiveな呼び出しを参照してください。

13.6 関数のマッピング

A mapping function applies a given function (not a special form or macro) to each element of a list or other collection. Emacs Lisp has several such functions; this section describes mapcar, mapc, mapconcat, and mapcan, which map over a list. See Definition of mapatoms, for the function mapatoms which maps over the symbols in an obarray. See Definition of maphash, for the function maphash which maps over key/value associations in a hash table.

これらのマップ関数は文字テーブル(char-table)には適用されません。なぜなら文字テーブルは非常に広い範囲の疎な配列だからです。疎な配列であるという性質に適う方法で文字テーブルにマッピングするには、関数map-char-tableを使用します(文字テーブルを参照)。

Function: mapcar function sequence

mapcarは関数functionをsequenceの各要素にたいして順番に適用して、その結果をリストでリターンする。

引数sequenceには、文字テーブルを除く任意の種類のシーケンス — つまりリスト、ベクター、ブールベクター、文字列を指定できる。結果は常にリストになる。結果の長さはsequenceの長さと同じ。たとえば:

(mapcar 'car '((a b) (c d) (e f)))
     ⇒ (a c e)
(mapcar '1+ [1 2 3])
     ⇒ (2 3 4)
(mapcar 'string "abc")
     ⇒ ("a" "b" "c")

;; my-hooks内の各関数を呼び出す
(mapcar 'funcall my-hooks)

(defun mapcar* (function &rest args)
  "Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
  ;; リストが消費されていなければ
  (if (not (memq nil args))
      ;; CARに関数を適用する
      (cons (apply function (mapcar 'car args))
            (apply 'mapcar* function
                   ;; 残りの要素のための再帰
                   (mapcar 'cdr args)))))

(mapcar* 'cons '(a b c) '(1 2 3 4))
     ⇒ ((a . 1) (b . 2) (c . 3))

Function: mapcan function sequence

This function applies function to each element of sequence, like mapcar, but instead of collecting the results into a list, it returns a single list with all the elements of the results (which must be lists), by altering the results (using nconc; see section リストを再配置する関数). Like with mapcar, sequence can be of any type except a char-table.

;; Contrast this:
(mapcar 'list '(a b c d))
     ⇒ ((a) (b) (c) (d))
;; with this:
(mapcan 'list '(a b c d))
     ⇒ (a b c d)

Function: mapc function sequence: mapcはmapcarと似ているが、functionは副作用のためだけに使用される — つまりfunctionがリターンする値は無視されてリストに収集されない。mapcは常にsequenceをリターンする。

Function: mapconcat function sequence separator

mapconcatはsequenceのそれぞれの要素にfunctionを適用する。結果は文字のシーケンス(文字列、ベクター、リスト)でなければならず、単一の文字列に結合されてリターン値となる。mapconcatは結果シーケーンスの各ペアの間にseparatorの文字を挿入する。これも文字列、または文字のベクターかリストでなければならない。シーケンス、配列、ベクターを参照のこと。

引数functionは1つの引数を受け取り文字のシーケンス、すなわち文字列、ベクター、リストのいずれかをリターンする。引数sequenceは文字テーブル以外の任意の種類のシーケンス、すなわちリスト、ベクター、ブールベクター、または文字列を指定できる。

(mapconcat 'symbol-name
           '(The cat in the hat)
           " ")
     ⇒ "The cat in the hat"

(mapconcat (function (lambda (x) (format "%c" (1+ x))))
           "HAL-8000"
           "")
     ⇒ "IBM.9111"

13.7 無名関数

関数は通常はdefunにより定義されて、同時に名前が与えられますが、明示的にラムダ式を使う — 無名関数(anonymous function)のほうが便利なときもあります。無名関数は名前つき関数が有効な場所ならどこでも有効です。無名関数は変数や関数の引数に割り当てられることがよくあります。たとえばある関数をリストの各要素に適用するmapcarのfunction引数に渡すかもしれません(関数のマッピングを参照)。現実的な例はdescribe-symbols exampleを参照してください。

無名関数として使用するためのラムダ式を定義するとき、原則的にはリストを構築する任意の手法を使用できます。しかし通常はマクロlambda、スペシャルフォームfunction、または入力構文#'を使用するべきです。

Macro: lambda args [doc] [interactive] body…

このマクロは引数リストargs、(もしあれば)ドキュメント文字列doc、(もしあれば)インタラクティブ指定interactive、およびbodyで与えられるbodyフォームをもつ無名関数をリターンする。

In effect, this macro makes lambda forms self-quoting: evaluating a form whose CAR is lambda yields the form itself:

(lambda (x) (* x x))
     ⇒ (lambda (x) (* x x))

lambdaフォームは別の1つの効果をもつ。このマクロはfunction(以下参照)をサブルーチンとして使用することにより、Emacs評価機能(Emacs evaluator)とバイトコンパイラーに、その引数が関数であることを告げる。

Special Form: function function-object

このスペシャルフォームは評価を行わずにfunction-objectをリターンする。この点ではquote(クォートを参照)と似ている。しかしquoteとは異なり、Emacs評価機能とバイトコンパイラーに、これを関数として使用する意図を告げる役割をもつ。function-objectが有効なラムダ式と仮定すると、これは２つの効果をもつ:

そのコードがバイトコンパイルされているとき、function-objectはバイトコード関数オブジェクトにコンパイルされる(バイトコンパイルを参照)。
レキシカルバインドが有効ならfunction-objectはクロージャーに変換される。クロージャーを参照のこと。

入力構文#'はfunctionの使用の略記です。以下のフォームは等価です:

(lambda (x) (* x x))
(function (lambda (x) (* x x)))
#'(lambda (x) (* x x))

以下の例では3つ目の引数に関数をとるchange-property関数を定義して、その後のchange-propertyで無名関数を渡してこれを使用しています:

(defun change-property (symbol prop function)
  (let ((value (get symbol prop)))
    (put symbol prop (funcall function value))))

(defun double-property (symbol prop)
  (change-property symbol prop (lambda (x) (* 2 x))))

lambdaフォームをクォートしていないことに注意してください。

上記のコードをコンパイルすると無名関数もコンパイルされます。リストをクォートすることにより無名関数を構築した場合にはコンパイルはされません。

(defun double-property (symbol prop)
  (change-property symbol prop '(lambda (x) (* 2 x))))

この場合、無名関数はコンパイルされたコード内のラムダ式に保持されます。バイトコンパイラーはchange-propertyが関数としての使用を意図していることを知ることができないので、たとえこの関数が関数のように見えるとしても、このリストが関数であると決め込むことができません。

13.8 Generic Functions

defunを使用して定義された関数は、その引数の型と期待する値に関して、ハードコードされた一連の仮定をもちます。たとえば数字か数字のリストを引数値として処理するようにデザインされた関数は、ベクターや文字列のような他の型の値で呼び出されると失敗したりエラーをシグナルするでしょう。これはその関数実装が、デザイン時に想定した以外の型に対応しないために発生します。

対照的に多相型関数(polymorphic functions)を使用したオブジェクト指向プログラムでは、同一の名前をもつ一連の特化した関数のそれぞれが、特定の引数型セットにたいして記述されます。どの関数が実際に呼び出されるかは、実際の引数の型にもとづいて実行時に決定されます。

Emacsはポリモーフィズム(polymorphism)にたいするサポートを提供します。他のLisp環境、特にCommon LispとCommon Lispオブジェクトシステム(CLOS)と同じように、このサポートはジェネリック関数(generic functions)を基礎としています。Emacsのジェネリック関数は同一名の使用を含むCLOSに密接にしたがっているので、CLOSの経験があればこのセクションの残りの部分は非常に身近に感じるでしょう。

ジェネリック関数は、その名前と引数のリストを指定して、(通常は)実装されていない抽象操作(abstract operation)を指定します。引数のいくつかの固有クラスにたいする実際の実装はメソッド(methods)により提供され、これは個別に定義されるべきです。ジェネリック関数を実装するそれぞれのメソッドはジェネリック関数としてとして同じ名前をもちますが、そのジェネリック関数で定義された引数のスペシャライジング(specializing)により、メソッドの定義はどの種類の引数を処理可能かを示します。これらの引数スペシャライザー(argument specializers)は多少の差はあれ特化したものにできます。たとえばstring型はsequenceのようなより一般的な型より特化した型です。

C++やSimulaのようなメッセージベースのOO言語と異なり、ジェネリック関数を実装するメソッドはクラスに属さずに、それらが実装するジェネリック関数に属することに注意してください。

ジェネリック関数が呼び出されると、呼び出し側に渡された実際の引数と各メソッドの引数スペシャライザーを比較することにより、適用可能なメソッドを呼び出します。その呼び出しの実際の引数がメソッドのスペシャライザーと互換性があれば、そのメソッドが適用可能です。複数のメソッドが適用可能ならば、それらは以下で説明する特定のルールにより合成されて、その組み合わせが呼び出しを処理します。

Macro: cl-defgeneric name arguments [documentation] [options-and-methods…] &rest body

このマクロは指定したnameとargumentsでジェネリック関数を定義する。bodyが与えられたなら、それは実装のデフォルトを与える。(常に与えられるべきであるが)documentationが与えられたなら、それは(:documentation docstring)の形式でそのジェネリック関数のドキュメント文字列を指定する。オプションのoptions-and-methodsは以下のフォームのいずれかを指定できる:

(declare declarations): declareフォームで説明するようなdeclareフォーム。
(:argument-precedence-order &rest args): このフォームは適用可能なメソッド合成にたいするソート順に影響を与える。合成において2つのメソッドを比較する際、メソッドの引数は通常は左から右に試験されて、引数スペシャライザーがより特化した最初のメソッドが他のメソッドより前になる。このフォームで定義された順序はそれをオーバーライドして、左から右ではなくこのフォームの順に応じて試験される。
(:method [qualifiers…] args &rest body): このメソッドはcl-defmethodが行うようなメソッドを定義する。

Macro: cl-defmethod name [qualifier] arguments &rest [docstring] body

このマクロはnameと呼ばれるジェネリック関数の、特定の実装を定義する。実装コードはbodyで与えられる。もし与えられたらdocstringはそのメソッドのドキュメント文字列である。リストargumentsはジェネリック関数を実装するすべてのメソッドで等しく、その関数の引数リストとマッチしなければならず、(arg spec)という形式の引数スペシャライザーを提供する。ここでargはcl-defgeneric呼び出しで指定された引数名、specは以下のスペシャライザーフォームのいずれかであること:

type: このスペシャライザーは、引数がtypeのいずれかであることを要求する。typeは以下で説明する型ヒエラルキーのいずれかの型である。
(eql object): このスペシャライザーは、引数がobjectとeqlであることを要求する。
(head object): 引数はcarがobjectとeqlであるようなコンスセルでなければならない。
struct-type: The argument must be an instance of a class named struct-type defined with cl-defstruct (see Structures in Common Lisp Extensions for GNU Emacs Lisp), or of one of its child classes.

かわりに引数スペシャライザーは&context (expr spec)という形式でもよく、この場合はexprの値はspecが提供するスペシャライザーと互換性がなければならない。specには以下で説明する任意のフォームを指定できる。言い換えると、このスペシャライザーのフォームはメソッドが適用可能かどうかの判定にたいして、引数のかわりにexprの値を使用する。たとえば&context (overwrite-mode (eql t))はoverwrite-modeがオンのときだけ互換性のあるメソッドを作成する。

型スペシャライザー(arg type)は以下のリストのシステム型(system types)のいずれかを指定できる。親の型が指定されたときは、型がより特化した子型、孫型、曾孫型、...のいずれかであるような任意の引数も互換となるだろう。

integer: 親型: number。
number
null: 親型: symbol。
symbol
string: 親型: array。
array: 親型: sequence。
cons: 親型: list。
list: 親型: sequence。
marker
overlay
float: 親型: number。
window-configuration
process
window
subr
compiled-function
buffer
char-table: 親型: array。
bool-vector: 親型: array。
vector: 親型: array。
frame
hash-table
font-spec
font-entity
font-object

オプションのqualifierは複数の適用可能なメソッドの合成を許容する。与えられなければ定義されるメソッドはprimary(主)メソッドとなり、スペシャライズされた引数にたいする主要な実装の提供に責任を有する。qualifierとして以下の値のいずれかを使用してauxiliary(副)メソッドも定義できる:

:before: このauxiliaryメソッドはprimaryメソッドの前に実行される。より正確にはすべての:beforeメソッドは、より特化したメソッドが最初になる順で、primaryメソッドの前に実行される。
:after: このauxiliaryメソッドはprimaryメソッドの後に実行される。より正確にはすべてのこの類のメソッドは、より特化したメソッドが最後になる順で、primaryメソッドの後に実行される。
:around: このauxiliaryメソッドはprimaryメソッドの代替えとして実行される。この類のメソッドでもっとも特化したものが他のメソッドより前に実行される。このようなメソッドは他のauxiliaryメソッドやprimaryメソッドを呼び出すために、通常は以下で説明するcl-call-next-methodを使用する。
:extra string: これにより同一のspecializerとqualifierにたいして、stringで区別されるメソッドを追加できる。

ジェネリック関数が呼び出されると、毎回その関数にたいして定義された適用可能なメソッドを合成することによってその呼び出しを処理するeffectiveメソッド(effective method)を構築します。適用可能なメソッドを探してeffectiveメソッドを生成するプロセスはdispatchと呼ばれます。その呼び出しの実際の引数と互換性があるスペシャライザーをもつすべてのメソッドが、互換性のあるメソッドです。すべての引数がスペシャライザーと互換でなければならないので、それらはすべてメソッドが適用可能かどうか判定します。複数の引数に明示的に特化したメソッドをmultiple-dispatchメソッド(multiple-dispatch methods)と呼びます。

適用可能なメソッドはそれらが合成される順にソートされます。最左の引数スペシャライザーがもっとも特化したものであるようなメソッドが、順序の最初になります(上述したようにcl-defmethodの一部として:argument-precedence-orderを指定することによりこれをオーバーライドできる)。そのメソッドのbodyがcl-call-next-methodを呼び出すと、もっとも特化した次のメソッドが実行されます。適用可能な:aroundメソッドがあれば、それらのうちもっとも特化したメソッドが実行されます。そのメソッドはより特化していない任意の:aroundメソッドを実行するために、cl-call-next-methodを呼び出すべきです。次に:beforeメソッドがその特化した順に、その後にspecificityメソッドが実行されます。そして後に:afterメソッドがその特化した順と逆順で実行されます。

Function: cl-call-next-method &rest args: primaryメソッドか:around auxiliaryメソッド内のレキシカルbody内で呼び出されると、同じジェネリック関数にたいして適用可能な次のメソッドを呼び出す。通常これは引数なしで呼び出され、これは次の適用可能なメソッドを呼び出すメソッドが、呼び出されたときと同じ引数で次のメソッドを呼び出すことを意味する。それ以外ならかわりに指定された引数が使用される。

Function: cl-next-method-p: primaryメソッドか:around auxiliaryメソッドのレキシカルbody内からこの関数を呼び出したときは、呼び出す次のメソッドが存在すれば非nilをリターンする。

13.9 関数セルの内容へのアクセス

あるシンボルの関数定義(function definition)とは、そのシンボルの関数セルに格納されたオブジェクトのことです。ここでは、シンボルの関数セルにアクセス、テスト、セットする関数を説明します。

Definition of indirect-functionの、関数indirect-functionも参照してください。

Function: symbol-function symbol

これはsymbolの関数セル内のオブジェクトをreturnします。これは、returnされたオブジェクトが本物のの関数であるかチェックしません。

関数セルがvoidの場合、return値はnilです。関数セルがvoidのときと、nilがセットされているときを区別するには、fboundp(以下参照)を使用します。

(defun bar (n) (+ n 2))
(symbol-function 'bar)
     ⇒ (lambda (n) (+ n 2))

(fset 'baz 'bar)
     ⇒ bar

(symbol-function 'baz)
     ⇒ bar

シンボルに何の関数定義も与えていない場合、そのシンボルの関数セルはvoidだと言います。言い換えると、その関数セルは、どんなLispオブジェクトも保持しません。そのシンボルを関数として呼びだそうとすると、Emacsはvoid-functionエラーをシグナルします。

voidは、nilやシンボルvoidとは異なることに注意してください。シンボルnilおよびvoidはLispオブジェクトであり、他のオブジェクトと同様、関数セルに格納することができます(これらのシンボルはdefunを使用して有効な関数に成ることができます)。voidである関数セルは、どのようなオブジェクトも含みません。

fboundpを使用して、任意のシンボルの関数定義がvoidかどうかテストすることができます。シンボルに関数定義を与えた後は、fmakunboundをつかえば、再びvoidにすることができます。

Function: fboundp symbol: この関数は、そのシンボルが関数セルにオブジェクトをもっていればt、それ以外はnilをreturnします。これは、そのオブジェクトが本物の関数であるかチェックしません。

Function: fmakunbound symbol

この関数はsymbolの関数セルをvoidにします。そのため、これ以降に関数セルにアクセスしようと試みると、void-functionエラーが発生します。これはsymbolをreturnします(When a Variable is Voidのmakunboundも参照してください)。

(defun foo (x) x)
(foo 1)
     ⇒1

(fmakunbound 'foo)
     ⇒ foo

(foo 1)
error→ Symbol's function definition is void: foo

Function: fset symbol definition

この関数はsymbolの関数セルに、definitionを格納します。結果はdefinitionです。definitionは通常、関数または関数の名前であるべきですが、これはチェックされません。引数symbolは、通常のどおり評価される引数です。

この関数は主に、関数を定義したり変更して構成を行う、defunやadvice-addのようなものからサブルーチンとして使用されます。シンボルにたいして、たとえばキーボードマクロ(キーボードマクロを参照してください)のような、関数ではない関数定義与えるためにも使用することができます:

;; 名前つきのキーボードマクロを定義する。
(fset 'kill-two-lines "\^u2\^k")
     ⇒ "\^u2\^k"

関数にたいして別の名前を作成するためにfsetを使いたい場合は、かわりにdefaliasの使用を考慮してください。Definition of defaliasを参照してください。

13.10 クロージャー

変数のバインディングのスコーピングルールで説明したように、Emacsはオプションで変数のレキシカルバインディングを有効にできます。レキシカルバインディングが有効な場合、あなたが(たとえばdefunなどで)作成した任意の名前つき関数、同様にlambdaマクロ、functionスペシャルフォーム、#'構文を使用して作成した任意の無名関数(無名関数を参照してください)は、自動的にクロージャー(closure)に変換されます。

クロージャーとは、その関数が定ぎされたどときに存在したレキシカル環境の記録もあわせもつ関数です。クロージャーが呼び出されたとき、定義内のレキシカル変数の参照には、その保持されたレキシカル環境を使用されます。他のすべての点では、クロージャーは通常の関数と同様に振る舞います。特に、クロージャーは通常の関数と同じ方法で呼び出すことができます。

クロージャー使用する例は、レキシカルバインディングを参照してください。

現在のところ、Emacs Lispのクロージャーオブジェクトは、1つ目の要素にシンボルclosureをもつリストとして表現されます。そのリストは2つ目の要素としてレキシカル環境を表し、残りの要素で引数リストとbodyフォームを表します:

;; レキシカルバインディングが有効。
(lambda (x) (* x x))
     ⇒ (closure (t) (x) (* x x))

However, the fact that the internal structure of a closure is exposed to the rest of the Lisp world is considered an internal implementation detail. For this reason, we recommend against directly examining or altering the structure of closure objects.

13.11 Emacs Lisp関数にたいするアドバイス

他のライブラリーの関数定義を変更する必要があるとき、またはfoo-functionoのようなフックやプロセスフィルター(process filter)、または関数を値としてもつ任意の変数またはオブジェクトを変更する必要があるときには、名前つきの関数にはfsetかdefun、フック変数にはsetq、プロセスフィルターにはset-process-filterのように、適切なセッター関数(setter function)を使用することができます。しかし、これらが以前の値を完全に破棄してしまうのが好ましくない場合もあります。

アドバイス(advice)機能により、関数にアドバイスすることにより、既存の関数定義に機能を追加できます。これは関数全体を再定義するより明解な手法です。

Emacsのアドバイスシステムは2つのプリミティブセットを提供します。コアとなるセットは、変数やオブジェクトのフィールドに保持された関数値にたいするものです(対応するプリミティブはadd-functionとremove-functionです)。もう1つのセットは、名前つき関数の最上位のレイヤーとなるものです(主要なプリミティブはadvice-addとadvice-removeです)。

たとえば、プロセスprocのプロセスフィルターの呼び出しをトレースするためには、以下を使用できます:

(defun my-tracing-function (proc string)
  (message "Proc %S received %S" proc string))

(add-function :before (process-filter proc) #'my-tracing-function)

これにより、そのプロセスの出力は、元のプロセスフィルターに渡される前に、my-tracing-functionに渡されるようになります。my-tracing-functionは元の関数と同じ引数を受け取ります。これを行った場合、以下のようにしてトレースを行わない振る舞いにリバートすることができます。

(remove-function (process-filter proc) #'my-tracing-function)

同様に、display-bufferという名前つきの関数の実行をトレースしたい場合は、以下を使用できます:

(defun his-tracing-function (orig-fun &rest args)
  (message "display-buffer called with args %S" args)
  (let ((res (apply orig-fun args)))
    (message "display-buffer returned %S" res)
    res))

(advice-add 'display-buffer :around #'his-tracing-function)

ここで、his-tracing-functionは元の関数のかわりに呼び出され、元の関数(加えてその関数の引数)を引数として受け取るので、必要な場合はそれを呼び出すことができます。出力を確認し終えたら、以下のようにしてトレースしない振る舞いにリバートできます:

(advice-remove 'display-buffer #'his-tracing-function)

The arguments :before and :around used in the above examples specify how the two functions are composed, since there are many different ways to do it. The added function is also called a piece of advice.

13.11.1 アドバイスを操作するためのプリミティブ

Macro: add-function where place function &optional props

このマクロはplace(ジェネリック変数を参照してください)に格納された関数に、アドバイスfunctionを追加する手軽な方法です。

where determines how function is composed with the existing function, e.g., whether function should be called before, or after the original function. See section Ways to compose advice, for the list of available ways to compose the two functions.

(通常は名前が-functionで終わる)変数を変更するときには、functionがグローバルに使用されるか、あるいはカレントバッファーだけに使用されるか選ぶことができます。placeが単にシンボルの場合、functionはplaceのグローバル値に追加されます。placeが(local symbol)というフォームの場合、symbolはその変数の名前をreturnする式なので、functionはカレントバッファーだけに追加されます。最後に、レキシカル変数を変更したい場合には、(var variable)を使用する必要があるでしょう。

add-functionで追加されたすべての関数は、自動的にプロパティーpropsの関連リストに加えることができます。現在のところ、特別な意味をもつのは2つのプロパティーだけです:

name

これはアドバイスの名前を与えます。この名前は、remove-functionが取り除く関数を識別するのに使用できます。これは通常、functionが無名関数のときに使用されます。

depth

This specifies how to order the advice, should several pieces of advice be present. By default, the depth is 0. A depth of 100 indicates that this piece of advice should be kept as deep as possible, whereas a depth of -100 indicates that it should stay as the outermost piece. When two pieces of advice specify the same depth, the most recently added one will be outermost.

For :before advice, being outermost means that this advice will be run first, before any other advice, whereas being innermost means that it will run right before the original function, with no other advice run between itself and the original function. Similarly, for :after advice innermost means that it will run right after the original function, with no other advice run in between, whereas outermost means that it will be run right at the end after all other advice. An innermost :override piece of advice will only override the original function and other pieces of advice will apply to it, whereas an outermost :override piece of advice will override not only the original function but all other advice applied to it as well.

functionがインタラクティブでない場合、欠オグされた関数は、(もしあれば)元の関数のインタラクティブ指定(interactive spec)を継承します。それ以外は、結合された関数はインタラクティブになり、functionのインタラクティブ指定を使用します。1つ例外があります。functionのインタラクティブ指定が、(式や文字列ではない)関数の場合、元の関数のインタラクティブ指定を唯一の引数として、その関数を呼び出して、それが結合された関数のインタラクティブ指定になります。引数として受け取ったインタラクティブ指定を解釈するためには、advice-eval-interactive-specを使用します。

注意: functionのインタラクティブ指定は結合された関数に適用され、functionではなく、結合された関数の呼び出し規約に従うべきです。多くの場合、これらは等しいので差異は生じませんが、functionの:around、:filter-args、filter-returnでは、重要になります。

Macro: remove-function place function

このマクロはplaceに格納された関数から、functionを取り除きます。これは、add-functionを使用して、functionがplaceに追加されたときだけ機能します。

functionは、placeに追加された関数にたいして、ラムダ式にたいしても機能するように、equalを使用して比較を試みます。これは追加でplaceに追加された関数のnameプロパティーも比較します。これはequalを使用してラムダ式を比較するより信頼性があります。

Function: advice-function-member-p advice function-def: adviceがすでにfunction-def内にある場合は、非nilをreturnします。上記のremove-functionと同様、実際の関数adviceのかわりに、アドバイス断片(piece of advice)のnameも使用できます。

Function: advice-function-mapc f function-def: Call the function f for every piece of advice that was added to function-def. f is called with two arguments: the advice function and its properties.

Function: advice-eval-interactive-spec spec: Evaluate the interactive spec just like an interactive call to a function with such a spec would, and then return the corresponding list of arguments that was built. E.g., (advice-eval-interactive-spec "r\nP") will return a list of three elements, containing the boundaries of the region and the current prefix argument.

13.11.2 名前つき関数にたいするアドバイス

アドバイスの一般的な使い方は、名前つき関数やマクロにたいして使用する方法です。これは単にadd-functionを使用して以下のように行うことができます:

(add-function :around (symbol-function 'fun) #'his-tracing-function)

But you should use advice-add and advice-remove for that instead. This separate set of functions to manipulate pieces of advice applied to named functions, offers the following extra features compared to add-function: they know how to deal with macros and autoloaded functions, they let describe-function preserve the original docstring as well as document the added advice, and they let you add and remove advice before a function is even defined.

既存の関数を関数全体を再定義せずに、既存の呼び出しを変更するために、advice-addは有用になります。しかし、その関数の既存の呼び出し元は、古い振る舞いを前提としているかもしれず、アドバイスによりその振る舞いが変更されたときに正しく機能しないかもしれないので、これはソースのバグにもなり得ます。アドバイスはデバッグを難しくする可能性もあります。デバッグを行う人は、その関数がアドバイスにより変更されたことに気づかなかったり、失念しているかもしれません。

これらの理由により、他の方法で関数の振る舞いを変更できない場合のために、アドバイスの使用は控えるべきです。フックを通じて同じことが行えるなら、フック(フックを参照してください)の使用が望ましい方法です。特定のキーが行う何かを変更したいだけなら、新しいコマンドを記述して、古いコマンドのキーバインドを新しいコマンドにリマップ(コマンドのリマップを参照してください)するのが、おそらくより良い方法です。特に、Emacs自身のソースファイルは、Emacs内の関数をアドバイスするべきではありません(現在のところこの慣習には数少ない例外がありますが、わたしたちはこれを改善しようと思っています)。

スペシャルフォーム(スペシャルフォームを参照してください)はアドバイスできませんが、マクロは関数と同じ方法でアドバイスできます。もちろん、これはすでにマクロ展開されたコードには影響しないため、マクロ展開前にアドバイスが確実にインストールされる必要があります。

プリミティブ(関数とは?を参照してください)にアドバイスするのは可能ですが、2つの理由により通常は行うべきではありません。1つ目の理由は、いくつかのプリミティブはアドバイスのメカニズム内で使用されているため、それらにたいしてアドバイスを行うと無限再帰が発生するからです。2つ目の理由は、多くのプリミティブがCから直接呼び出されていて、そのような呼び出しはアドバイスを無視するからです。したがって、プリミティブにたいしてアドバイスの使用を控えることは、ある呼び出しはアドバイスにしたがい(Lispコードから呼びだされたため)、他の呼び出しではアドバイスにしたがわない(Cコードから呼び出されたため)という混乱した状況を解決します。

Macro: define-advice symbol (where lambda-list &optional name depth) &rest body: This macro defines a piece of advice and adds it to the function named symbol. The advice is an anonymous function if name is nil or a function named symbol@name. See advice-add for explanation of other arguments.

Function: advice-add symbol where function &optional props: 名前つき関数symbolに、アドバイスfunctionを追加します。whereとpropsは、add-function(アドバイスを操作するためのプリミティブを参照してください)のときと同じ意味をもちます。

Function: advice-remove symbol function: Remove the advice function from the named function symbol. function can also be the name of a piece of advice.

Function: advice-member-p function symbol: Return non-nil if the advice function is already in the named function symbol. function can also be the name of a piece of advice.

Function: advice-mapc function symbol: Call function for every piece of advice that was added to the named function symbol. function is called with two arguments: the advice function and its properties.

13.11.3 Ways to compose advice

以下はadd-functionおよびadvice-addのwhere引数に可能な値で、そのアドバイスfunctionと元の関数が構成されるべき方法を指定します。

:before

古い関数の前にfunctionを呼び出します。関数は両方とも同じ引数を受け取り、2つの関数の結合のreturn値は、古い関数のreturn値です。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (apply function r) (apply oldfun r))

(add-function :before funvar function)は、ノーマルフックにたいする(add-hook 'hookvar function)のような、1関数のフックと同等です。

:after

古い関数の後にfunctionを呼び出します。関数は両方とも同じ引数を受け取り、2つの関数の結合のreturn値は、古い関数のreturn値です。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (prog1 (apply oldfun r) (apply function r)))

(add-function :after funvar function)は、ノーマルフックにたいする(add-hook 'hookvar function 'append)のような、1関数のフックと同等です。

:override

これは古い関数を新しい関数に完全に置き換えます。もちろん、remove-functionを呼び出した後に、古い関数は復元されます。

:around

古い関数のかわりにfunctionを呼び出しますが、古い関数はfunctionの追加の引数になります。これはもっとも柔軟な結合です。たとえば、古い関数を異なる引数で呼び出したり、複数回呼び出したり、letバインディングで呼び出したり、あるときは古い関数に処理を委譲し、またあるときは完全にオーバーライドすることが可能になります。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (apply function oldfun r))

:before-while

古い関数の前にfunctionを呼び出し、functionがnilをreturnした場合は古い関数を呼び出しません。関数は両方とも同じ引数を受け取り、2つの関数の結合のreturn値は、古い関数のreturn値です。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (and (apply function r) (apply oldfun r)))

(add-function :before-while funvar function)は、run-hook-with-args-until-failureを通じてhookvarが実行されたときの(add-hook 'hookvar function)のような、1関数のフックと同等です。

:before-until

古い関数の前にfunctionを呼び出し、functionがnilをreturnした場合だけ古い関数を呼び出します。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (or (apply function r) (apply oldfun r)))

(add-function :before-until funvar function) は、run-hook-with-args-until-successを通じてhookvarが実行されたときの(add-hook 'hookvar function)のような、1関数のフックと同等です。

:after-while

古い関数が非nilをreturnした場合だけ、古い関数の後にfunctionを呼び出します。関数は両方とも同じ引数を受け取り、2つの関数の結合のreturn値は、functionのreturn値です。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (and (apply oldfun r) (apply function r)))

(add-function :after-while funvar function)は、run-hook-with-args-until-failureを通じてhookvarが実行されたときの(add-hook 'hookvar function 'append)のような、1関数のフックと同等です。

:after-until

古い関数がnilをreturnした場合だけ、古い関数の後にfunctionを呼び出します。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (or  (apply oldfun r) (apply function r)))

(add-function :after-until funvar function)は、run-hook-with-args-until-successを通じてhookvarが実行されたときの(add-hook 'hookvar function 'append)のような、1関数のフックと同等です。

:filter-args

最初にfunctionを呼び出し、その結果(リスト)を新たな引数として古い関数に渡します。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (apply oldfun (funcall function r)))

:filter-return

最初に古い関数を呼び出し、その結果をfunctionに渡します。より正確に言うと、2つの関数の結合は、以下のように振る舞います:

(lambda (&rest r) (funcall function (apply oldfun r)))

13.11.4 古いdefadviceを使用するコードの改良

多くのコードは古いdefadviceメカニズムを使用しており、これらの大半はadvice-addにより陳腐化しました。advice-addの実装と意味は、とてもシンプルです。

An old piece of advice such as:

(defadvice previous-line (before next-line-at-end
                                 (&optional arg try-vscroll))
  "Insert an empty line when moving up from the top line."
  (if (and next-line-add-newlines (= arg 1)
           (save-excursion (beginning-of-line) (bobp)))
      (progn
        (beginning-of-line)
        (newline))))

新しいアドバイスメカニズムを使用すれば、これを通常の関数に変換できます:

(defun previous-line--next-line-at-end (&optional arg try-vscroll)
  "Insert an empty line when moving up from the top line."
  (if (and next-line-add-newlines (= arg 1)
           (save-excursion (beginning-of-line) (bobp)))
      (progn
        (beginning-of-line)
        (newline))))

これが実際のprevious-lineを変更しないことは明確です。古いアドバイスには、以下が必要です:

(ad-activate 'previous-line)

一方、新しいアドバイスメカニズムでは、以下が必要です:

(advice-add 'previous-line :before #'previous-line--next-line-at-end)

Note that ad-activate had a global effect: it activated all pieces of advice enabled for that specified function. If you wanted to only activate or deactivate a particular piece, you needed to enable or disable it with ad-enable-advice and ad-disable-advice. The new mechanism does away with this distinction.

Around advice such as:

(defadvice foo (around foo-around)
  "Ignore case in `foo'."
  (let ((case-fold-search t))
    ad-do-it))
(ad-activate 'foo)

これは以下のように変換できます:

(defun foo--foo-around (orig-fun &rest args)
  "Ignore case in `foo'."
  (let ((case-fold-search t))
    (apply orig-fun args)))
(advice-add 'foo :around #'foo--foo-around)

Regarding the advice’s class, note that the new :before is not quite equivalent to the old before, because in the old advice you could modify the function’s arguments (e.g., with ad-set-arg), and that would affect the argument values seen by the original function, whereas in the new :before, modifying an argument via setq in the advice has no effect on the arguments seen by the original function. When porting before advice which relied on this behavior, you’ll need to turn it into new :around or :filter-args advice instead.

Similarly old after advice could modify the returned value by changing ad-return-value, whereas new :after advice cannot, so when porting such old after advice, you’ll need to turn it into new :around or :filter-return advice instead.

13.12 関数を陳腐と宣言する

名前つき関数を陳腐化している(obsolete)とマークすることができます。これは、その関数が将来のある時点で削除されるかもしれないことを意味します。陳腐化しているとマークされた関数を含むコードをバイトコンパイルしたとき、Ｅｍａｃｓは警告を発します。また、その関数のヘルプドキュメントは表示されなくなります。他の点においては、陳腐化した関数は他の任意の関数と同様に振る舞います。

関数を陳腐化しているとマークするもっとも簡単な方法は、その関数のdefun定義に(declare (obsolete …))を配置することです。declareフォームを参照してください。かわりに、以下で説明しているmake-obsolete関数を使うこともできます。

make-obsoleteを使用して、マクロ(マクロを参照してください)を陳腐化しているとマークすることもできます。これは関数のときと同じ効果をもちます。関数またはマクロにたいするエイリアスも、陳腐化しているとマークできます。これはエイリアス自身をマークし、名前解決される関数またはマクロにたいしてではありません。

Function: make-obsolete obsolete-name current-name &optional when

この関数は、obsolete-nameを陳腐化しているとマークします。obsolete-nameには関数またはマクロを名前づけるシンボル、、または関数やマクロにたいするエイリアスを指定します。

current-nameがシンボルの場合は、obsolete-nameのかわりにcurrent-nameの使用を促す警告メッセージになります。current-nameは、obsolete-nameにたいするエイリアスである必要はありません。似たような機能をもつ、別の関数かもしれません。current-nameには、警告メッセージとなる文字列も指定できます。メッセージは小文字で始まりピリオドで終えるべきです。nilも指定でき、この場合には警告メッセージに追加の詳細は提供されません。

whenが与えられた場合、それは最初にその関数が陳腐化する時期を示す文字列 — たとえば火付けやリリース番号を指定します。

Macro: define-obsolete-function-alias obsolete-name current-name &optional when doc

この便利なマクロは関数obsolete-nameを陳腐化しているとマークするとともに、それを関数current-nameのエイリアスにします。これは以下と等価です:

(defalias obsolete-name current-name doc)
(make-obsolete obsolete-name current-name when)

In addition, you can mark a particular calling convention for a function as obsolete:

Function: set-advertised-calling-convention function signature when

この関数は、functionを呼び出す正しい方法として、引数リストsignatureを指定します。これにより、Emacs Lispプログラムが他の方法でfunctionを呼び出している場合には、Emacsのバイトコンパイラーが警告を発します(それでもコードはバイトコンパイルされます)。whenには、その変数が最初に陳腐化するときを示す文字列(通常はバージョン番号)を指定します。

たとえば、古いバージョンのEmacsでは、sit-forには以下のように3つの引数を指定していました

  (sit-for seconds milliseconds nodisp)

しかしこの方法によるsit-forの呼び出しは陳腐化していると判断されます(時間の経過や入力の待機を参照してください)。以下のように、古い呼び出し規約は推奨されません:

(set-advertised-calling-convention
  'sit-for '(seconds &optional nodisp) "22.1")

13.13 インライン関数Inline Functions

インライン関数(inline function)は関数と同様に機能しますが、1つ例外があります。その関数の呼び出しがバイトコンパイルされると(バイトコンパイルを参照してください)、その関数の定義が呼び出し元に展開されます。インライン関数を定義するには、defunのかわりにdefsubstを使用します。

Macro: defsubst name args [doc] [declare] [interactive] body…: このマクロはインライン関数を定義します。マクロの構文はdefunとまったく同じです(関数の定義を参照してください)。

関数をインラインにすることにより、その関数の呼び出しが高速になる場合があります。しかし欠点もあります。1つは柔軟性の減少です。その関数の定義を変更した場合、すでにインライン化された呼び出しは、リコンパイルを行うまで古い定義を使用します。

もう1つの欠点は、大きな関数をインライン化することにより、コンパイルされたコードのファイル上およびメモリー上のサイズが増大することです。スピード面でのインライン化の有利性は小さい関数にたいして顕著なので、一般的に大きな関数をインライン化するべきではありません。

インライン関数は、デバッグ、トレース、アドバイス(Emacs Lisp関数にたいするアドバイスを参照してください)に際してうまく機能しません。デバッグの容易さと関数の再定義の柔軟さはEmacsの重要な機能なので、スピードがとても重要であり、defunの使用が実際に性能の面で問題となるのか検証するためにすでにコードをチューニングしたのでなければ、たとえその関数が小さくてもインライン化するべきではありません。

インライン関数を定義した後、そのインライン展開はマクロ同様、同じファイル内の後の部分で処理されます。

It’s possible to use defmacro to define a macro to expand into the same code that an inline function would execute (see section マクロ). But the macro would be limited to direct use in expressions—a macro cannot be called with apply, mapcar and so on. Also, it takes some work to convert an ordinary function into a macro. To convert it into an inline function is easy; just replace defun with defsubst. Since each argument of an inline function is evaluated exactly once, you needn’t worry about how many times the body uses the arguments, as you do for macros.

As an alternative to defsubst, you can use define-inline to define functions via their exhaustive compiler macro. See section define-inline.

13.14 `declare`フォーム

declare is a special macro which can be used to add meta properties to a function or macro: for example, marking it as obsolete, or giving its forms a special TAB indentation convention in Emacs Lisp mode.

Macro: declare specs…

このマクロは引数を無視して、nilとして評価され、実行時の効果はありません。しかしdefunまたはdefsubst(関数の定義を参照してください)、またはdefmacroマクロ(マクロの定義を参照してください)の定義のdeclare引数にdeclareフォームがある場合は、specsで指定されたプロパティーを関数またはマクロに追加します。これはdefun、defsubst、defmacroにより特別に処理されます。

specs内の各要素は(property args…)というフォームをもつべきです。また、クォートするべきではありません。これらは、以下の効果をもちます:

(advertised-calling-convention signature when): これはset-advertised-calling-convention(関数を陳腐と宣言するを参照してください)の呼び出しと同じように振る舞います。signatureはその関数(またはマクロにたいする正しい引数リスト)で、whenは古い引数リストが最初に陳腐化する時期を示す文字列を指定します。
(debug edebug-form-spec): これはマクロだけに有効です。Edebugでそのマクロ入ったときに、edebug-form-specを使用します。マクロ呼び出しのインストルメントを参照してください。
(doc-string n): それ自身が関数、マクロ、または変数のようなエンティティーを定義するために使用される関数やマクロを定義するときに使用されます。これはn番目の引数を示し、もしあれば、それはドキュメント文字列です。
(indent indent-spec): この関数(またはマクロ)にたいするインデント呼び出しは、indent-specにしたがいます。これは関数でも機能しますが、通常はマクロで使用されます。マクロのインデントを参照してください。
(interactive-only value): Set the function’s interactive-only property to value. See The interactive-only property.
(obsolete current-name when): make-obsolete(関数を陳腐と宣言するを参照してください)と同様に、関数(またはマクロ)を陳腐化しているとマークします。current-nameにはシンボル(かわりにこのシンボルを使うことをすすめる警告メッセージになります)、文字列(警告メッセージを指定します)、またはnil(警告メッセージには追加の詳細が含まれません)を指定します。whenには、その関数(またはマクロ)が最初に陳腐化する時期を示す文字列を指定します。
(compiler-macro expander): これは関数だけに使用でき、最適化関数(optimization function)としてexpanderを使用するようコンパイラーに告げます。(function args…)のようなその関数への呼び出しフォームに出会うと、マクロ展開機能(macro expander)はargs…と同様のフォームでexpanderを呼び出します。expanderはその関数呼び出しのかわりに使用するための新しい式、または変更されていないフォーム(その関数呼び出しを変更しないことを示す)のどちらかをreturnすることができます。expanderにはシンボル、またはフォーム(lambda (arg) body)を指定できます。フォームの場合、argは元の関数呼び出し式を保持して、その関数の形式に適う引数を使用することにより、その関数にたいする(評価されていない)引数にアクセスできます。
(gv-expander expander): expanderがgv-define-expanderと同様、汎変数としてマクロ(または関数)にたいする呼び出しを処理する関数であることを宣言します。expanderはシンボル、またはフォーム(lambda (arg) body)を指定できます。フォームの場合、その関数は追加でそのマクロ(または関数)にアクセスできます。
(gv-setter setter): setterが、汎変数としてマクロ(または関数)にたいする呼び出しを処理する関数であることを宣言します。setterはシンボル、またはフォームを指定できます。シンボルの場合、そのシンボルはgv-define-simple-setterに渡されます。フォームの場合は(lambda (arg) body)という形式で、その関数は追加でマクロ(または関数)にアクセスでき、gv-define-setterに渡されます。

13.15 コンパイラーへの定義済み関数の指示

Byte-compiling a file often produces warnings about functions that the compiler doesn’t know about (see section コンパイラーのエラー). Sometimes this indicates a real problem, but usually the functions in question are defined in other files which would be loaded if that code is run. For example, byte-compiling simple.el used to warn:

simple.el:8727:1:Warning: the function ‘shell-mode’ is not known to be
    defined.

In fact, shell-mode is used only in a function that executes (require 'shell) before calling shell-mode, so shell-mode will be defined properly at run-time. When you know that such a warning does not indicate a real problem, it is good to suppress the warning. That makes new warnings which might mean real problems more visible. You do that with declare-function.

必要なのは、問題となっている関数を最初に使用する前にdeclare-function命令を追加するだけです:

(declare-function shell-mode "shell" ())

This says that shell-mode is defined in shell.el (the ‘.el’ can be omitted). The compiler takes for granted that that file really defines the function, and does not check.

The optional third argument specifies the argument list of shell-mode. In this case, it takes no arguments (nil is different from not specifying a value). In other cases, this might be something like (file &optional overwrite). You don’t have to specify the argument list, but if you do the byte compiler can check that the calls match the declaration.

Macro: declare-function function file &optional arglist fileonly: Tell the byte compiler to assume that function is defined in the file file. The optional third argument arglist is either t, meaning the argument list is unspecified, or a list of formal parameters in the same style as defun. An omitted arglist defaults to t, not nil; this is atypical behavior for omitted arguments, and it means that to supply a fourth but not third argument one must specify t for the third-argument placeholder instead of the usual nil. The optional fourth argument fileonly non-nil means check only that file exists, not that it actually defines function.

これらの関数がdeclare-functionが告げる場所で実際に宣言されているか検証するには、check-declare-fileを使用して、1つのソースファイル中のすべてのdeclare-function呼び出しをチェックするか、check-declare-directoryを使用して、特定のディレクトリー配下のすべてのファイルをチェックします。

これらのコマンドは、locate-libraryで使用する関数の定義を含むべきファイルを探します。ファイルが見つからない場合、これらのコマンドはdeclare-functionの呼び出しを含むファイルをがあるディレクトリーからの相対ファイル名に、定義ファイル名を展開します。

‘.c’や‘.m’で終わるファイル名を指定することにより、プリミティブ関数を指定することもできます。これが有用なのは、特定のシステムだけで定義されるプリミティブを呼び出す場合だけです。ほとんどのプリミティブは常に定義されているので、それらについて警告を受け取ることはありえないはずです。

あるファイルがオプションとして外部のパッケージの関数を使う場合があります。declare-function命令内のファイル名のプレフィクスを‘ext:’にすると、そのファイルが見つかった場合はチェックして、見つからない場合はエラーとせずにスキップします。

‘check-declare’が理解しない関数定義もいくつか存在します(たとえばdefstructや、その他いくつかのマクロ)。そのような場合、declare-functionのfileonly引数に、非nilを渡すことができます。これはファイルの存在だけをチェックして、その関数の実際の定義はチェックしないことを意味します。これを行う場合、引数リストを指定する必要はないのですが、arglist引数にはtをセットするべきだということに注意してください(なぜならnilは、引数リストが指定されなかったという意味ではなく、空の引数リストを意味するからです)。

13.16 安全に関数を呼び出せるかどうかの判断

SESのようないくつかのメジャーモードは、ユーザーファイル内に格納された関数を呼び出します(See (ses)Top, for more information on SESを参照してください)。ユーザーファイルには素性があやふやな場合があります — 初対面の人から受け取ったスプレッドシートかもしれず、会ったことのない誰かから受け取ったeメールかもしれません。そのため、ユーザーファイルに格納されたソースコードの関数を呼び出すのは、それが安全だと決定されるすまでは危険です。

Function: unsafep form &optional unsafep-vars: formが安全(safe)なLisp式の場合はnil、危険な場合はなぜその式が危険かもしれないのか説明するリストをreturnします。引数unsafep-varsは、この時点で一時的なバインドだと判っているシンボルのリストです。これは主に内部的な再帰呼び出しで使用されます。カレントバッファーは暗黙の引数になり、これはバッファーローカルなバインディングのリストを提供します。

Being quick and simple, unsafep does a very light analysis and rejects many Lisp expressions that are actually safe. There are no known cases where unsafep returns nil for an unsafe expression. However, a safe Lisp expression can return a string with a display property, containing an associated Lisp expression to be executed after the string is inserted into a buffer. This associated expression can be a virus. In order to be safe, you must delete properties from all strings calculated by user code before inserting them into buffers.

13.17 関数に関するその他トピック

以下のテーブルは、関数呼び出しと関数定義に関連したことを行ういくつかの関数です。これらは別の場所で説明されているので、ここではクロスリファレンスを提供します。

apply: 関数の呼び出しを参照してください。
autoload: autoloadを参照してください。
call-interactively: interactiveな呼び出しを参照してください。
called-interactively-p: interactiveな呼び出しの区別を参照してください。
commandp: interactiveな呼び出しを参照してください。
documentation: ドキュメント文字列へのアクセスを参照してください。
eval: evalを参照してください。
funcall: 関数の呼び出しを参照してください。
function: 無名関数を参照してください。
ignore: 関数の呼び出しを参照してください。
indirect-function: シンボル関数インダイレクションを参照してください。
interactive: interactiveの使用を参照してください。
interactive-p: interactiveな呼び出しの区別を参照してください。
mapatoms: シンボルの作成とinternを参照してください。
mapcar: 関数のマッピングを参照してください。
map-char-table: 文字テーブルを参照してください。
mapconcat: 関数のマッピングを参照してください。
undefined: キー照合のための関数を参照してください。

14 マクロ

マクロ(macros)は、新たな制御構造や、他の言語機能の定義を可能にします。マクロは関数のように定義されますが、値の計算方法を指定するかわりに、値を計算する別のLisp式を計算する方法を指示します。わたしたちはこの式のことをマクロの展開形(expansion)と呼んでいます。

マクロは、関数が行うように引数の値を処理するのではなく、引数のために未評価の式を処理することにより、これを行うことができます。したがってマクロは、これらの引数式またはその一部をを含む式を構築することができます。

マクロを使用して通常の関数が行えることを行う場合、単にそれが速度面の理由ならば、かわりにインライン関数の使用を考慮してください。インライン関数Inline Functionsを参照してください。

14.1 単純なマクロの例		基本的な例。
14.2 マクロ呼び出しの展開		いつ、なぜ、どのようにしてマクロが展開されるか。
14.3 マクロとバイトコンパイル		コンパイラーによりマクロが展開される方法。
14.4 マクロの定義		マクロ定義を記述する方法。
14.5 マクロ使用に関する一般的な問題		マクロ引数を何回も評価しないこと。ユーザーの変数を隠さないこと。
14.6 マクロのインデント		マクロ呼び出しのインデント方法の指定。

14.1 単純なマクロの例

Cの++演算子のように、変数の値をインクリメントするためのLisp構造を定義したいとします。(inc x)のように記述すると、(setq x (1+ x))という効果を得たいとします。以下はこれを行うマクロ定義です:

(defmacro inc (var)
   (list 'setq var (list '1+ var)))

これを(inc x)のように呼び出すと、引数varはシンボルxになります — 関数のときのようにxの値ではありません。このマクロのbodyはこれを展開の構築に使用して、展開形は(setq x (1+ x))になります。マクロが一度この展開形をreturnすると。Lispはそれを評価するので、xはインクリメントされます。

Function: macrop object: この術後は、その引数がマクロかどうかテストして、もしマクロならt、それ以外はnilをreturnします。

14.2 マクロ呼び出しの展開

マクロ呼び出しは、関数の呼び出しと同じ外観をもち、マクロの名前で始まるリストで表されます。そのリストの残りの要素は、マクロの引数になります。

マクロ呼び出しの評価は、1つの重大な違いを除き、関数の評価と同じように開始されます。重要な違いとは、そのマクロの引数はマクロ呼び出し内で実際の式として現れます。これらの引数はマクロ定義に与えられる前には評価されません。対象的に、関数の引数は、その関数の呼び出しリストの要素を評価した結果です。

こうして得た引数を使用して、Lispは関数呼び出しのように、マクロ定義を呼び出します。マクロの引数変数はマクロ呼び出しの引数値にバインドされるか、a &rest引数の場合は引数地のリストになります。そして、そのマクロのbodyが実行されて、関数bodyが行うように、マクロbodyの値をreturnsします。

マクロと関数の2つ目の重要な違いは、マクロのbodyからreturnされる値が、代替となるLisp式であることで、これはマクロの展開(expansion)としても知られます。Lispインタープリターは、マクロから展開形が戻されると、すぐにその展開形の評価を行います。

展開形は通常の方法で評価されるので、もしかしたらその展開形は他のマクロの呼び出しを含むかもしれません。一般的ではありませんが、もしかすると同じマクロを呼び出すかもしれません。

EmacsはコンパイルされていないLispファイルをロードするときに、マクロの展開を試みることに注意してください。これは常に利用可能ではありませんが、もし可能なら、それ以降の実行の速度を改善します。プログラムがロードを行う方法を参照してください。

macroexpandを呼び出すことにより、与えられたマクロ呼び出しにたいする展開形を確認することができます。

Function: macroexpand form &optional environment

この関数は、それがマクロ呼び出しの場合は、formを展開します。結果が他のマクロ呼び出しの場合は、結果がマクロ呼び出しでなくなるまで、順番に展開を行います。これはmacroexpandからreturnされる値になります。formがマクロ呼び出しで開始されない場合、与えられたformをそのままreturnします。

macroexpandは、(たとえいくつかのiマクロ定義がそれを行っているとしても)formの部分式(subexpression)を調べないことに注意してください。たとえ部分式自身がマクロ呼び出しの場合でも、macroexpandはそれらを展開しません。

関数macroexpandは、インライン関数の呼び出しを展開しません。なぜならインライン関数の呼び出しは、通常の関数呼び出しと比較して理解が難しい訳ではないので、通常はそれを行う必要がないからです。

environmentが与えられた場合、それはそのとき定義されているマクロをシャドーするマクロのalistを指定します。バイトコンパイルはこの機能を使用します。

(defmacro inc (var)
    (list 'setq var (list '1+ var)))

(macroexpand '(inc r))
     ⇒ (setq r (1+ r))

(defmacro inc2 (var1 var2)
    (list 'progn (list 'inc var1) (list 'inc var2)))

(macroexpand '(inc2 r s))
     ⇒ (progn (inc r) (inc s))  ; ここではincは展開されない。

Function: macroexpand-all form &optional environment

macroexpand-allはmacroexpandと同様、マクロを展開しますが、ドップレベルだけではなく、form内のすべてのマクロを探して展開します。展開されたマクロがない場合、return値は、formとeqになります。

上記macroexpandで使用した例をmacroexpand-allに用いると、macroexpand-allがincに埋め込まれた呼び出しの展開を行うことを確認できます:

(macroexpand-all '(inc2 r s))
     ⇒ (progn (setq r (1+ r)) (setq s (1+ s)))

Function: macroexpand-1 form &optional environment: This function expands macros like macroexpand, but it only performs one step of the expansion: if the result is another macro call, macroexpand-1 will not expand it.

14.3 マクロとバイトコンパイル

なぜわざわざマクロにたいする展開形を計算して、その後に展開形を評価する手間をかけるのか、不思議に思うかもしれません。なぜマクロbodyは直接望ましい結果を生成しないのでしょうか? それはコンパイルする必要があるからです。

コンパイルされるLispプログラム内にマクロ呼び出しがあるとき、Lispコンパイラーはインタープリターが行うようにマクロ定義を呼び出して、展開形を受け取ります。しかし展開形を評価するかわりに、コンパイラーは展開形が直接プログラム内にあるかのようにコンパイルを行います。結果として、コンパイルされたコードはそのマクロにたいする値と副作用を生成しますが、実行速度は完全にコンパイルされた行されたときと同じになります。もしマクロbody自身が値と副作用を計算したら。このようには機能しません — コンパイル時に計算されることになり、それは有用ではありません。

マクロ呼び出しのコンパイルが機能するためには、マクロを呼び出すコードがコンパイルされるとき、そのマクロがLisp内ですでに定義されていなければなりません。コンパイラーには、これを行うのを助ける特別な機能があります。コンパイルされるファイルがdefmacroフォームを含む場合、そのファイルの残りの部分をコンパイルするために、そのマクロが一時的に定義されます。

ファイルをバイトコンパイルすると、ファイル内のトップレベルにある任意のrequire呼び出しも実行されるので、それらを定義しているファイルをrequireすることにより、コンパイルの間、必要なマクロ定義が利用できることが確実になります(名前つき機能を参照してください)。誰かがコンパイルされたプログラムを実行するときに、マクロ定義ファイルのロードをしないようにするには、require呼び出しの周囲にeval-when-compileを記述します(コンパイル中の評価を参照してください)。

14.4 マクロの定義

Lispのマクロオブジェクトは、CARがmacroで、CDRが関数のリストです。マクロの展開形は、マクロ呼び出しから、評価されていない引数のリストに、(applyを使って)関数を適用することにより機能します。

無名関数のように無名Lispマクロを使用することも可能ですが、無名マクロをmapcarのようなファンクショナルに渡すことに意味がないので、これが行われることはありません。実際のところ、すべてのLispマクロは名前をもち、ほとんど常にdefmacroマクロで定義されます。

Macro: defmacro name args [doc] [declare] body…

defmacroはシンボルname(クォートはしない)を、以下のようなマクロ押して定義します:

(macro lambda args . body)

(このリストのCDRはラムダ式であることに注意してください。) このマクロオブジェクトは、nameの関数セルに格納されます。argsの意味は関数の場合と同じで、キーワード&restおよび&optionalが使用されることもあります(引数リストのその他機能を参照してください)。nameとargsはどちらも、クォートされるべきではありません。defmacroのreturn値は未定義です。

docが与えられた場合、それはマクロのドキュメント文字列を指定する文字列です。declareが与えられた場合、それはマクロのメタデータを指定するdeclareフォームです(declareフォームを参照してください)。マクロを対話的に呼び出すことはできないので、インタラクティブ宣言をもつことはできないことに注意してください。

マクロが、定数部と非定数部の混合体から構築される巨大なリスト構造を必要とする場合があります。これを簡単に行うためには、‘`’構文(バッククォートを参照してください)を使用します。たとえば:

(defmacro t-becomes-nil (variable)
  `(if (eq ,variable t)
       (setq ,variable nil)))

(t-becomes-nil foo)
     ≡ (if (eq foo t) (setq foo nil))

14.5 マクロ使用に関する一般的な問題

マクロ展開が、直感に反する結果となることがあり得ます。このセクションでは、問題になりかねない重要な結果と、問題を避けるためにしたがうべきルールをいくつか説明します。

14.5.1 タイミング間違い		マクロ内ではなく展開形で作業を行う。
14.5.2 マクロ引数の多重評価		展開形は各マクロ引数を一度評価すること。
14.5.3 マクロ展開でのローカル変数		展開形でのローカル変数バインディングには特に注意を要する。
14.5.4 展開におけるマクロ引数の評価		評価せずに展開形の中に配置すること。
14.5.5 マクロが展開される回数は?		展開が行われる回数への依存を避ける。

14.5.1 タイミング間違い

マクロを記述する際のもっとも一般的な問題は、展開形の中ではなく、マクロ展開中に、早まって実際に何らかの作業を行ってしまうことがあります。たとえば、実際のパッケージが以下のマクロ定義をもつとします:

(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)
      (set-buffer-multibyte arg)))

この誤ったマクロ定義は、解釈(interpret)されるときは正常に機能しますが、コンパイル時に失敗します。このマクロ定義はコンパイル時にset-buffer-multibyteを呼び出してしまいますが、それは間違っています。その後でコンパイルされたパッケージを実行しても何も行いません。プログラマーが実際に望むのは、以下の定義です:

(defmacro my-set-buffer-multibyte (arg)
  (if (fboundp 'set-buffer-multibyte)
      `(set-buffer-multibyte ,arg)))

このマクロは、もし適切ならset-buffer-multibyteの呼び出しに展開され、それはコンパイルされたプログラム実行時に実行されるでしょう。

14.5.2 マクロ引数の多重評価

When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The following macro (used to facilitate iteration) illustrates the problem. This macro allows us to write a for-loop construct.

(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  (list 'let (list (list var init))
        (cons 'while
              (cons (list '<= var final)
                    (append body (list (list 'inc var)))))))

(for i from 1 to 3 do
   (setq square (* i i))
   (princ (format "\n%d %d" i square)))
→

(let ((i 1))
  (while (<= i 3)
    (setq square (* i i))
    (princ (format "\n%d %d" i square))
    (inc i)))


     -|1       1
     -|2       4
     -|3       9
⇒ nil

The arguments from, to, and do in this macro are syntactic sugar; they are entirely ignored. The idea is that you will write noise words (such as from, to, and do) in those positions in the macro call.

以下は、バッククォートの使用により、より単純化された等価の定義です:

(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  `(let ((,var ,init))
     (while (<= ,var ,final)
       ,@body
       (inc ,var))))

この定義のフォームは両方(バッククォートのあるものと、ないもの)とも、各繰り返しにおいて毎回finalが評価されるという欠点をもちます。finalが定数のときには、問題はありません。しかし、これがより複雑な、たとえば(long-complex-calculation x)のようなフォームの場合、実効速度は顕著に低下し得ます。finalが副作用をもつ場合には、複数回実行すると、おそらく正しくなくなります。

うまく設計されたマクロ定義は、繰り返し評価することがそのマクロの意図された目的でない限り、引数を正確に1回評価を行う展開形を生成することにより、この問題を避けるためにステップを費やします。以下はforマクロの正しい展開形です:

(let ((i 1)
      (max 3))
  (while (<= i max)
    (setq square (* i i))
    (princ (format "%d      %d" i square))
    (inc i)))

以下はこの展開形を生成するためのマクロ定義です:

(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  `(let ((,var ,init)
         (max ,final))
     (while (<= ,var max)
       ,@body
       (inc ,var))))

残念なことに、この訂正により、以下のセクションで説明する、別の問題が発生します。

14.5.3 マクロ展開でのローカル変数

前のセクションでは、forの定義を、展開形がマクロ引数を正しい回数評価するように訂正しました:

(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."

  `(let ((,var ,init)
         (max ,final))
     (while (<= ,var max)
       ,@body
       (inc ,var))))

forの新しい定義には、新たな問題があります。この定義は、ユーザーが意識していない、maxという名前のローカル変数を導入しています。これは、以下の例で示すようなトラブルを招きます:

(let ((max 0))
  (for x from 0 to 10 do
    (let ((this (frob x)))
      (if (< max this)
          (setq max this)))))

forのbodyの内部のmaxへの参照は、maxのユーサーバインディングの参照を意図したものですが、実際にはforにより作られたバインディングにアクセスします。

これを修正する方法は、maxのかわりにinternされていない(uninterned)シンボルを使用することです(シンボルの作成とinternを参照してください)。internされていないシンボルは他のシンボルと同じようにバインドして参照することができますが、forにより作成されるので、わたしたちはすでにユーザーのプログラムに存在するはずがないことを知ることができます。これはinternされていないので、プログラムの後続の部分でそれを配置する方法はありません。これはforにより配置された場所をのぞき、他の場所で配置されることはありません。以下はこの方法で機能するforの定義です:

(defmacro for (var from init to final do &rest body)
  "Execute a simple for loop: (for i from 1 to 10 do (print i))."
  (let ((tempvar (make-symbol "max")))
    `(let ((,var ,init)
           (,tempvar ,final))
       (while (<= ,var ,tempvar)
         ,@body
         (inc ,var)))))

作成されたinternされていないシンボルの名前はmaxで、これを通常のinternされたシンボルmaxのかわりに、式内のその位置に記述します。

14.5.4 展開におけるマクロ引数の評価

マクロ定義自体が、eval(evalを参照してください)の呼び出しなどによりマクロ引数式を評価した場合には、別の問題が発生します。その引数がユーザーの変数を参照する場合、ユーザーがマクロ引数と同じな前で変数をしようとした場合に問題となるでしょう。マクロのbodyないでは、マクロ引数のバインディングは、その変数のもっともローカルなバインディングなので、そのフォーム内部の任意の参照は、それを参照するように評価されます。以下は例です:

(defmacro foo (a)
  (list 'setq (eval a) t))

(setq x 'b)
(foo x) → (setq b t)
     ⇒ t                  ; bがセットされる。
;; but
(setq a 'c)
(foo a) → (setq a t)
     ⇒ t                  ; しかし、これはcではなくaがセットされる。

ユーザーの変数の名前がaかxかということで、違いが生じています。これはaが、マクロの引数変数aと競合しているからです。

マクロ定義内でのevalの呼び出しにまつわる別の問題は、それがおそらくコンパイル時にあなたが意図したことを行わないだろうということです。バイトコンパイラーは、そのプログラム自身の(あなたがevalでアクセスしたいと望む)計算は発生せず、ローカル変数バインディングも存在しないプログラムのコンパイル時にマクロ定義を実行します。

この問題を避けるためには、マクロ展開形の計算では引数式を評価しないでください。かわりにその式をマクロ展開形の中に置き換えれば、その値は展開形の実行の一部として計算されます。これは、このチャプターの他の例が機能する方法です。

14.5.5 マクロが展開される回数は?

マクロ呼び出しは逐次解釈される関数で毎回マクロ呼び出しが展開されるが、コンパイルされた関数では(コンパイル時に)1回だけしか展開されないという事実にもとづく問題が、時折発生します。そのマクロ定義が副作用をもつ場合、それらのマクロは、そのマクロが難解展開されたかにより、異なる動作をとるでしょう。

したがって、あなたが何をしているか本当に判っていないのであれば、マクロ展開形の計算での副作用は避けるべきです。

避けることのできない特殊な副作用が1つあります。それはLispオブジェクトの構築です。ほとんどすべてのマクロ展開形には、リストの構築が含まれます。リスト構築はほとんどのマクロの核心部分です。これは通常は安全です。用心しなければならないケースが1つだけあります。それは構築するオブジェクトが、マクロ展開形の中でクォートされた定数の一部となるときです。

そのマクロが1回だけ — コンパイル時 — しか展開されない場合、そのオブジェクトの構築もコンパイル時の1回です。しかし逐次実行では、そのマクロはマクロ呼び出しが実行されるたびに展開され、これは毎回新たなオブジェクトが構築されることを意味します。

クリーンなLispコードのほとんどでは、この違いは問題になりません。しかし、マクロ定義によるオブジェクト構築の副作用を処理する場合には、問題になるかもしれません。したがって問題を避けるために、マクロ定義によるオブジェクト構築の副作用を避けてください。以下は副作用により問題が起こる例です:

(defmacro empty-object ()
  (list 'quote (cons nil nil)))

(defun initialize (condition)
  (let ((object (empty-object)))
    (if condition
        (setcar object condition))
    object))

If initialize is interpreted, a new list (nil) is constructed each time initialize is called. Thus, no side effect survives between calls. If initialize is compiled, then the macro empty-object is expanded during compilation, producing a single constant (nil) that is reused and altered each time initialize is called.

このような異常な状態を避ける1つの方法は、empty-objectを、メモリー割り当て構造ではなく、一種の奇妙な変数と考えることです。'(nil)のような定数にたいしてsetcarを使うことはないでしょうから、当然(empty-object)にも使うことはないでしょう。

14.6 マクロのインデント

マクロ定義では、マクロ呼び出しをTABがどのようにインデントすべきか指定するために、declareフォーム(マクロの定義を参照してください)を使うことができます。インデント指定は以下のように記述します:

(declare (indent indent-spec))

This results in the lisp-indent-function property being set on the macro name.

以下は利用できるindent-specです:

nil

これはプロパティーを指定しない場合と同じ — 標準的なインデントパターンを使用します。

defun

この関数を‘def’構造 — 2番目の行がbodyの開始 — と同様に扱います。

整数: number

関数の最初のnumber個の引数は区別され、残りは式のbodyと判断されます。その式の中の行は、最初の引数が区別されているかどうかにしたがってインデントされます。引数がbodyの一部である場合、その行はこの式の先頭の開きカッコ(open-parenthesis)よりもlisp-body-indentだけ多い列にインデントされます。引数が区別されていて、1つ目または2つ目の引数である場合は、2倍余分にインデントされます。引数が区別されていて1つ目あるいは2つ目の引数でない場合、その行は標準パターンによってインデントされます。

シンボル: symbol

symbolは関数名です。その関数はこの式のインデントを計算するために呼び出される関数です。この関数は2つの引数をとります:

pos: その行のインデントが開始される位置です。
state: その行の開始まで解析されたとき、parse-partial-sexp(インデントとネスト深さの計算のためのLispプリミティブ)によりreturnされる値です。

これは、数(その行のインデントの列数)、またはそのような数がcarであるようなリストをreturnすべきです。数とリストの違いは、数の場合、同じネスト深さの後続のすべての行はこの数と同じインデントとなります。リストの場合、後続の行は異なるインデントを呼び出すかもしれません。これは、C-M-qによりインデントが計算されるときに違いがでます。値が数の場合、C-M-qはリストの終わりまでの後続の行のインデントを、再計算する必要はありません。

15 カスタマイズ設定

Emacsのユーザーは、カスタマイズインターフェースにより、Lispコードを記述することなく。変数とフェースをカスタマイズできます。Easy Customization in The GNU Emacs Manualを参照してください。このチャプターでは、カスタマイズインターフェースを通じて、ユーザーとやりとりするための、カスタマイズアイテム（customization items）を定義する方法を説明します。

カスタマイズアイテムには、カスタマイズ可能変数(customizable variable: defcustomマクロで定義される。カスタマイズ可能フェース(customizable face: deffaceで定義される。フェイスの定義を参照してください)、および関連するカスタマイズアイテムのグループのためのコンテナーとして働くカスタマイズグループ(customization group: defgroupで定義される) が含まれます。

15.1 一般的なキーワードアイテム		すべての種類のカスタマイズ宣言に共通なキーワード引数。
15.2 カスタマイズグループの定義		カスタマイズグループ定義の記述。
15.3 カスタマイズ変数の定義		ユーザーオプションの宣言。
15.4 カスタマイズ型		ユーザーオプションの型指定。
15.5 カスタマイズの適用		カスタマイズセッティングを適用する関数。
15.6 カスタムテーマ		カスタムテーマの記述。

15.1 一般的なキーワードアイテム

以降のセクションで説明するカスタマイズ宣言(customization declaration) — defcustom、defgroupなどはすべて、さまざまな情報を指定するためのキーワード引数(変更不可な変数を参照してください)を受け取ります。このセクションでは、カスタマイズ宣言のすべての種類に適用されるキーワードを説明します。

:tag以外のすべてのキーワードは、与えられたアイテムにたいして複数回使用できます。キーワードの使用はそれぞれ独立した効果をもちます。:tagは例外で、これはすべての与えられたアイテムは1つの名前だけを表示できるからです。

:tag label

labelを使用すると、カスタマイズメニュー(customization menu)およびカスタマイズバッファー(customization buffer)のアイテムのラベルづけに、そのアイテムの名前のかわりに指定された文字列を使用します。混乱を招くので、そのアイテムの実際の名前と、大きく異なる名前は使用しないでください。

:group group

Put this customization item in group group. If this keyword is missing from a customization item, it’ll be placed in the same group that was last defined (in the current file).

When you use :group in a defgroup, it makes the new group a subgroup of group.

このキーワードを複数回使用した場合、1つのアイテムを複数のグループに配すことができます。これらのグループのどれかを表示すると、このアイテムが表示されます。煩わしくなるので、多用しないでください。

:link link-data

このアイテムのドキュメント文字列の後に外部リンクを含めます。これは他のドキュメントを参照する、センテンスを含むボタンです。

link-dataに使用できる複数の候補があります:

(custom-manual info-node): infoノードへのリンクです。info-nodeは、"(emacs)Top"のような、ノード名を示す文字列です。このリンクはカスタマイズバッファーの‘[Manual]’に表示され、info-nodeにたいしてビルトインのinfoリーダーを起動します。
(info-link info-node): custom-manualと同様ですが、カスタマイズバッファーには、そのinfoノード名が表示されます。
(url-link url): ウェブページヘのリンクです。urlはURLを指定する文字列です。カスタマイズバッファーに表示されるリンクは、browse-url-browser-functionで指定されたWWWブラウザーを呼び出します。
(emacs-commentary-link library): ライブラリーのコメントセクション(commentary section)へのリンクです。libraryはライブラリー名を指定する文字列です。Emacsライブラリーのヘッダーの慣習を参照してください。
(emacs-library-link library): Emacs Lispライブラリーファイルへのリンクです。libraryはライブラリー名を指定する文字列です。
(file-link file): ファイルへのリンクです。fileは、ユーザーがこのリンクを呼び出したときにfind-fileでvisitするファイルの名前を指定する文字列です。
(function-link function): 関数のドキュメントへのリンクです。functionは、ユーザーがこのリンクを呼び出したときにdescribe-functionで説明を表示する関数の名前を指定する文字列です。
(variable-link variable): 変数のドキュメントへのリンクです。variableは、ユーザーがこのリンクを呼び出したときにdescribe-variableで説明を表示する変数の名前を指定する文字列です。
(custom-group-link group): 他のカスタマイズグループへのリンクです。このリンクを呼び出すことにより、groupにたいする新たなカスタマイズバッファーが作成されます。

link-dataの1つ目の要素の後に:tag nameを追加することにより、カスタマイズバッファーで使用するテキストを指定できます。たとえば(info-link :tag "foo" "(emacs)Top")は、そのバッファーで‘foo’と表示されるEmacs manualへのリンクを作成します。

複数のリンクを追加するために、このキーワードを複数回使用することができます。

:load file

このカスタマイズアイテムを表示する前に、ファイルfileをロードします(ロードを参照してください)。ロードはloadにより行われ、そのファイルがまだロードされていないときだけロードします。

:require feature

保存したカスタマイズが、このアイテム値をセットするとき、(require 'feature)が実行されます。featureはシンボルです。

:requireを使用するもっとも一般的な理由は、ある変数がマイナーモードのような機能を有効にするとき、そのモードを実装するコードがロードされていない場合には、変数をセットするだけでは効果がないからです。

:version version

このキーワードは、そのアイテムが最初に導入されたEmacsバージョンversion、またはそのアイテムのデフォルト値がそのバージョンで変更されたことを指定します。値versionは文字列でなければなりません。

:package-version '(package . version)

このキーワードは、そのアイテムが最初に導入されたpackageのバージョンversionまたはアイテムの意味(またはデフォルト値)が変更されたバージョンを指定します。このキーワードは:versionより優先されます。

packageにはそのパッケージの公式名をシンボルとして指定します(たとえばMH-E)。versionには文字列を指定します。パッケージpackageがEmacsの一部としてリリースされた場合、packageとversionの値は、customize-package-emacs-version-alistの値に表示されるべきです。

Emacsの一部として配布された:package-versionキーワードを使用するパッケージは、customize-package-emacs-version-alist変数も更新しなければなりません。

Variable: customize-package-emacs-version-alist

このalistは、Emacsのバージョンにたいして、:package-versionキーワード内でリストされたパッケージのバージョンへのマッピングを提供します:

(package (pversion . eversion)…)

package(シンボル)それぞれにたいして、パッケージバージョンpversionを含む1つ以上の要素と、それに関連づけられるEmacsバージョンeversionが存在します。これらのバージョンは文字列です。たとえばMH-Eパッケージは、以下でalistを更新します:

(add-to-list 'customize-package-emacs-version-alist
             '(MH-E ("6.0" . "22.1") ("6.1" . "22.1") ("7.0" . "22.1")
                    ("7.1" . "22.1") ("7.2" . "22.1") ("7.3" . "22.1")
                    ("7.4" . "22.1") ("8.0" . "22.1")))

packageの値は一意である必要があり、また:package-versionキーワード内に現れるpackageの値とマッチする必要があります。おそらくユーザーはエラーメッセージからこの値を見るので、MH-EやGnusのようなパッケージの公式名を選択するのがよいでしょう。

15.2 カスタマイズグループの定義

Emacs Lispパッケージはそれぞれ、1つのメインカスタマイズグループ(main customization group)をもち、それにはすべてのオプション、フェイス、そのパッケージ内の他のグルーﾌﾟが含まれるべきです。そのパッケージには少数のオプションとフェイスしかない場合は、1つのグループだけを使用して、その中にすべてを置きます。20以上のオプションやフェイスがある場合には、それらをサブグループ内に構造化して、そのサブグループをメインカスタマイズグループの下に配します。そのパッケージ内の任意のオプションまたはフェイスを、サブグループと並行してメイングループに配しても構いません。

そのパッケージのメイングループ(または唯一のグループ)は、1つ以上の標準カスタムグループ(standard customization group)のメンバーであるべきです(これらの完全なリストを表示するには、M-x customizeを使用します)。それらの内から1つ以上(多すぎないこと)を選択して、:groupを使用してあなたのグループをそれらに追加します。

新しいカスタマイズグループは、defgroupで宣言します。

Macro: defgroup group members doc [keyword value]…

membersを含む、カスタマイズグループとして、groupを宣言します。シンボルgroupはクォートしません。引数docは、そのグループにたいするドキュメント文字列を指定します。

引数membersは、そのグループのメンバーとなるカスタマイズアイテムの初期セットを指定するリストです。しかしほとんどの場合はmembersをnilにして、メンバーを定義するときに:groupキーワードを使用することにより、そのグループのメンバーを指定します。

membersを通じてグループのメンバーを指定したい場合、各要素は(name widget)という形式で指定するべきです。ここでnameはシンボル、widgetはそのシンボルを編集するウィジェット型(widget type)です。有用なウィジェットには、変数にたいするcustom-variable、フェイスにたいするcustom-face、グループにたいするcustom-groupがあります。

Emacsに新しいグループを導入するときは、defgroup内で:versionキーワードを使用します。そうすればグループの個別のメンバーに対してそれを使用する必要がなくなります。

一般的なキーワード(一般的なキーワードアイテムを参照してください)に加えて、defgroupないでは以下のキーワードも使用できます:

:prefix prefix: グループ内のアイテムの名前がprefixで始まり、カスタマイズ変数custom-unlispify-remove-prefixesが非nilの場合、そのアイテムのタグからprefixが省略されます。グループは任意の数のプレフィクスをもつことができます。

The variables and subgroups of a group are stored in the custom-group property of the group’s symbol. See section シンボルのプロパティへのアクセス. The value of that property is a list of pairs whose car is the variable or subgroup symbol and the cdr is either custom-variable or custom-group.

User Option: custom-unlispify-remove-prefixes

この変数が非nilの場合、グループの:prefixキーワードで指定されたプレフィクスは、ユーザーがグループをカスタマイズするときは常に、タグ名から省略されます。

デフォルト値はnil、つまりプレフィクス省略(prefix-discarding)の機能は無効です。これは、オプションやフェイスの名前にたいしてプレフィクスを省略するのは、混乱を招くことがあるからです。

15.3 カスタマイズ変数の定義

カスタマイズ可能変数(customizable variable)はユーザーオプション(user option)とも呼ばれ、これはCustomizeインターフェースを通じてセットできるグローなるなLisp変数です。defvar(グローバル変数の定義を参照してください)により定義される他のグローバル変数とは異なり、カスタマイズ可能変数はdefcustomマクロを使用して定義されます。サブルーチンとしてdefvarを呼び出すことに加え、defcustomはCustomizeインターフェースでその変数が表示される方法や、その変数がとることができる値などを明示します。

Macro: defcustom option standard doc [keyword value]…

このマクロはユーザーオプション(またはカスタマイズ可能変数)としてoptionを宣言します。optionはクォートするべきではありません。

引数standardは、optionの標準値を指定する式です。defcustomフォームの評価により、standardが評価されますが、その値にオプションをバインドする必要はありません。optionがすでにデフォルト値をもつ場合、それは変更されずに残ります。ユーザーがすでにoptionにたいするカスタマイズを保存している場合、ユーザーによりカスタマイズされた値がデフォルト値としてインストールされます。それ以外は、standardを評価した結果がデフォルト値としてインストールされます。

defvarと同様、このマクロはoptionをスペシャル変数 — 常にダイナミックにバインドされるべきことを意味する — としてマークします。optionがすでにレキシカルバインドをもつ場合、そのレキシカルバインドはバインディング構造を抜けるまで効果をもちます。変数のバインディングのスコーピングルールを参照してください。

式standardは別の様々な機会にも — カスタマイズ機能がoptionの標準値を知る必要があるときは常に — 評価される可能性があります。そのため任意回数評価しても安全な式を使用するように気をつけてください。

引数docは、その変数にたいするドキュメント文字列を指定します。

defcustomが何も:groupを指定しない場合、同じファイル内でdefgroupにより最後に定義されたグループが使用されます。この方法では、ほとんどのdefcustomは明示的な:groupが必要なくなります。

Emacs LispモードでC-M-x(eval-defun)によりdefcustomフォームを評価するとき、eval-defunの特別な機能は、変数の値がvoidかどうかテストせず、無条件に変数をセットする段取りをします(同じ機能はdefvarにも適用されます。グローバル変数の定義を参照してください)。すでに定義されたdefcustomでeval-defunを使用することにより、(もしあれば):set関数が呼び出されます(以下参照)。

事前ロード( pre-loaded)されたEmacs Lispファイル(Emacsのビルドを参照してください)にdefcustomを配した場合、ダンプ時にインストールされた標準値は正しくない — たとえば依存している他の変数は、まだ正しい値を割り当てられていない —　かもしれません。この場合、Emacs起動後に標準値を再評価するために、以下で説明するcustom-reevaluate-settingを使用します。

一般的なキーワードアイテムにリストされたキーワードに加え、このマクロには以下のキーワードを指定できます:

:type type

Use type as the data type for this option. It specifies which values are legitimate, and how to display the value (see section カスタマイズ型). Every defcustom should specify a value for this keyword.

:options value-list

このオプションに使用する適正な値のリストを指定します。ユーザーが使用できる値はこれらの値に限定されませんが、これらは便利な候補値を提示します。

これは特定の型にたいしてだけ意味をもち、現在のところhook、plist、alistが含まれます。:optionsの使用法の説明は、個別の型の定義を参照してください。

:set setfunction

Customizeインターフェースを使用してこのオプションの値を変更する方法として、setfunctionを指定します。関数setfunctionは2つの引数 — シンボル(オプション名)と新しい値 — をとり、このオプションにたいして正しく値を更新するために必要なことは何であれ行うべきです(これはおそらくLisp変数として単にオプションをセットすることを意味しないでしょう)。望ましくは、この関数は引数の値を破壊的に変更するべきではありません。setfunctionのデフォルトは、set-defaultです。

このキーワードを指定した場合、その変数のドキュメント文字列には、手入力のLispコードで同じことを行う方法が記載されるべきです。

:get getfunction

Specify getfunction as the way to extract the value of this option. The function getfunction should take one argument, a symbol, and should return whatever customize should use as the current value for that symbol (which need not be the symbol’s Lisp value). The default is default-value.

:getを正しく使用するためには、Customの機能を真に理解する必要があります。これは変数としてCustom内で扱われる値のためのものですが、実際にはLisp変数に格納されません。実際にLisp変数に格納されている値にgetfunctionを指定するのは、ほとんどは誤りです。

:initialize function

functionは、defcustomが評価されるときに変数を初期化するために使用される関数であるべきです。これは2つの引数 — オプション名(シンボル)と値をとります。この方法での使用のために事前定義された関数がいくつかあります:

custom-initialize-set

変数の初期化に、その変数の:set関数を使用しますが、値がすでに非voidの場合、再処帰化を行いません。

custom-initialize-default

custom-initialize-setと同様ですが、その変数の:setのかわりに、関数set-defaultを使用して変数をセットします。これは変数の:set関数がマイナーモードを有効または無効にする場合の、通常の選択です。この選択により、変数の定義ではマイナーモード関数を呼び出しませんが、変数をカスタマイズしたときはマイナーモード関数を呼び出します。

custom-initialize-reset

変数の初期化に、常に:set関数を使用します。変数がすでに非voidの場合、(:getメソッドでreturnされる)カレント値を使用して:set関数を呼び出して変数をリセットします。これはデフォルトの:initialize関数です。

custom-initialize-changed

変数がすでにセットされている、またはカスタマイズされている場合は、変数の初期化のために:set関数を使用し、それ以外は単にset-defaultを使用します。

custom-initialize-safe-set

custom-initialize-safe-default

これらのn関数はcustom-initialize-set、custom-initialize-defaultと同様に振る舞いますが、エラーをcatchします。初期化中にエラーが発生した場合は、set-defaultを使用して変数をnilにセットして、エラーをシグナルしません。

これらの関数は事前ロードされたファイルで定義されたオプションのためのものです(requireされた変数または関数がまだ定義されていないため、standard式はエラーをシグナルするかもしれない)。その値は通常、startup.elで更新され、defcustomにより計算された値は無視されます。startup後に、その値をunsetして、defcustomを再評価すれば、エラーなしでstandardは評価されます。

:risky value

その変数のrisky-local-variableプロパティーをvalueにセットします(ファイルローカル変数を参照してください)。

:safe function

その変数のsafe-local-variableプロパティーを、functionにセットします(ファイルローカル変数を参照してください)。

:set-after variables

保存されたカスタマイズに合わせて変数をセッティングするときは、その前に変数variables確実にセット — つまり、これら他のものが処理される後までセッティングを遅延 — してください。これら他の変数が意図された値をもっていない場合に、この変数のセッティングが正しく機能しないときは、:set-afterを使用してください。

It is useful to specify the :require keyword for an option that turns on a certain feature. This causes Emacs to load the feature, if it is not already loaded, whenever the option is set. See section 一般的なキーワードアイテム. Here is an example, from the library saveplace.el:

(defcustom save-place nil
  "Non-nil means automatically save place in each file..."
  :type 'boolean
  :require 'saveplace
  :group 'save-place)

あるカスタマイズアイテムが、:optionsがサポートするhookやalistのような型をもつ場合は、custom-add-frequent-valueを呼び出すことにより、defcustom宣言の外部から、別途値を追加できます。たとえばemacs-lisp-mode-hookから呼び出されることを意図した関数my-lisp-mode-initializationを定義する場合は、emacs-lisp-mode-hookにたいする正当な値として、その定義を編集することなく、その関数をリストに追加したいと思うかもしれません。これは以下のようにして行うことができます:

(custom-add-frequent-value 'emacs-lisp-mode-hook
   'my-lisp-mode-initialization)

Function: custom-add-frequent-value symbol value

カスタマイズオプションsymbolにたいして正当な値のリストにvalueを追加します。

追加による正確な効果は、symbolのカスタマイズ型に依存します。

内部的には、defcustomは、標準値にたいする式を記録するためにシンボルプロパティーstandard-valueを、カスタマイズバッファーでユーザーによりセットされたが保存されていない値を記録するためにsaved-valueを使用します。シンボルのプロパティを参照してください。これらのプロパティーは、carがその値を評価する式であるようなリストです。

Function: custom-reevaluate-setting symbol

この関数は、defcustomを通じて宣言されたユーザーオプションsymbolの標準値を再評価します。変数がカスタマイズされた場合、この関数はかわりに保存された値を再評価します。それからこの関数はユーザーオプションをその値に(もし定義されていればそのオプションの:setプロパティーを使用して)セットします。

これは値が正しく計算される前に定義されたカスタマイズ可能オプションにたいして有用です。たとえばstartupの間、Emacsは事前ロードされたEmacs Lispファイルで定義されたユーザーオプションにたいしてこの関数を呼び出しますが、これらの初期値は実行時だけ利用可能な情報に依存します。

Function: custom-variable-p arg: この関数は、argがカスタマイズ可能変数の場合は、非nilをreturnします。カスタマイズ可能変数とは、standard-valueかcustom-autoloadプロパティーをもつ(通常はdefcustomで宣言されたことを意味する)変数、または別のカスタマイズ可能変数にたいするエイリアスのことです。

15.4 カスタマイズ型

defcustomでユーザーオプションを定義するときは、ユーザーオプションのカスタマイズ型(customization type)を指定しなければなりません。これは、(1)値が適正か、(2)編集のためにカスタマイズバッファーで値を表示する方法、を記述するLispオブジェクトです。

カスタマイズ型は、defcustom内の:typeキーワードで指定します。:typeの引数は評価されますが、defcustomが実行されるとき1回だけ評価されるので、さまざまな値をとる場合には有用でありません。通常はクォートされた定数を使用します。たとえば:

(defcustom diff-command "diff"
  "The command to use to run diff."
  :type '(string)
  :group 'diff)

一般的に、カスタマイズ型は、最初の要素が以降のセクションで定義されるカスタマイズ型の1つであるような、リストです。このシンボルの後にいくつかの引数があり、それはそのシンボルに依存します。型シンボルと引数の間には、オプションでkeyword-valueペアー(型キーワードを参照してください)を記述できます。

いくつかの型シンボルは引数を使用しません。これらはシンプル型(simple types)と呼ばれます。シンプル型にたいしては、keyword-valueペアーを使用しない場合は、型シンボルの周囲のカッコ(parentheses)を省略できます。たとえばカスタマイズ型として単にstringと記述すると、それは(string)と等価です。

すべてのカスタマイズ型はウィジェットとして実装されます。詳細は、Introduction in The Emacs Widget Libraryを参照してください。

15.4.1 単純型

このセクションでは、すべてのシンプルデータ型を説明します。これらのカスタマイズ型のうちのいくつかにたいして、カスタマイズウィジェットはC-M-iまたはM-TABによる、インライン補完を提供します。

sexp: 値はプリントおよび読み込むことができる任意のLispオブジェクトです。より特化した型の使用するために時間をとりたくない場合は、任意のオプションへのフォールバックとしてsexpを使用することができます。
integer: 値は整数でなければなりません。
number: 値は数(浮動小数点数または整数)でなければなりません。
float: 値は浮動小数点数でなければなりません。
string: 値は文字列でなければなりません。カスタマイズバッファーはその文字列を区切り文字‘"’文字および‘\’クォートなしで表示します。
regexp: string文字と同様ですが、その文字列は有効な正規表現でなければなりません。
character: 値は文字コードでなければなりません。文字コードは実際には整数ですが、この型は数字を表示せずに、バッファー内にその文字を挿入することにより値を表示します。
file: 値はファイル名でなければなりません。ウィジェットは補完を提供します。
(file :must-match t): 値は既存のファイル名でなければなりません。ウィジェットは補完を提供します。
directory: The value must be a directory. The widget provides completion.
hook: 値は関数のリストでなければなりません。このカスタマイズ型はフック変数にたいして使用されます。フック内での使用を推奨される関数のリストを指定するために、フック変数のdefcustom内で:optionsキーワードを使用できます。カスタマイズ変数の定義を参照してください。
symbol: 値はシンボルでなければなりません。これはカスタマイズバッファー内でシンボル名として表示されます。ウィジェットは補完を提供します。
function: 値はラムダ式か関数名でなければなりません。ウィジェットは関数名にたいする補完を提供します。
variable: 値は変数名でなければなりません。ウィジェットは補完を提供します。
face: 値はフェイス名のシンボルでなければなりません。ウィジェットは補完を提供します。
boolean: 値は真偽値 — nilかtです。choiceとconstを合わせて使用(次のセクションを参照)することにより、値がnilかtでなければならず、それぞれの値に固有の意味に適合する説明テキストを指定することもできます。
key-sequence: 値はキーシーケンスです。カスタマイズバッファーは、kbd関数と同じ構文うぃ使用して、キーシーケンスを表示します。キーシーケンスを参照してください。
coding-system: 値はコーディングシステム名でなければならず、M-TABで保管することができます。
color: 値は有効なカラー名でなければなりません。ウィジェットはカラー名にたいする補完と、同様に*Colors*バッファーに表示されるカラーサンプルとカラー名のリストからカラー名を選択するボタンを提供します。

15.4.2 複合型

適切なシンプル型がないときは、複合型(composite types)を使うことができます。複合型は特定のデータによる他の型から、新しい型を構築します。指定された型またはデータは、その複合型の引数(argument)と呼ばれます。複合型は通常、以下のようなものです:

(constructor arguments…)

しかし、以下のように引数の前にkeyword-valueペアーを追加することもできます。

(constructor {keyword value}… arguments…)

以下のテーブルに、はコンストラクター(constructor)と、複合型を記述するためにそれらを使用する方法を示します:

(cons car-type cdr-type)

値はコンスセルでなければならず、CARはcar-type、CDRはcdr-typeに適合していなければなりません。たとえば、(cons string symbol)は、("foo" . foo)のような値にマッチするデータ型です。

カスタマイズバッファーでは、CARとCDRは、それぞれ特定のデータ型に応じて、別々に表示・編集されます。

(list element-types…)

値は、element-typesで与えられる要素と数が正確に一致するリストでなければならず、リストの各要素はそれぞれ対応するelement-typeに適合しなければなりません。

たとえば、(list integer string function)は、３つの要素のリストを示し、１つ目の要素は整数、２つ目の要素は文字列、３つ目の要素は関数です。

カスタマイズバッファーでは、各要素は、それぞれ特定のデータ型に応じて、別々に表示・編集されます。

(group element-types…)

これはlistと似ていますが、Customバッファー内でのテキストのフォーマットが異なります。listは各要素の値を、そのタグでラベルづけしますが、groupはそれを行いません。

(vector element-types…)

これはlistと似ていますが、リストではなくベクターでなければなりません。各要素はlistの場合と同様に機能します。

(alist :key-type key-type :value-type value-type)

値はコンスセルのリストでなければならず、各セルのCARはカスタマイズ型key-typeのキーを表し、同じセルのCDRはカスタマイズ型value-typeの値を表します。ユーザーはkey/valueペアーの追加や削除ができ、各ペアのキーと値の両方を編集することができます。

省略された場合、key-typeとvalue-typeのデフォルトは、sexpです。

ユーザーは指定されたkey-typeにマッチする任意のキーを追加できますが、:options(カスタマイズ変数の定義を参照してください)で指定することにより、あるキーを優先的に扱うことができます。指定されたキーは、(適切な値とともに)常にカスタマイズバッファーに表示されます。また、alistにkey/valueを含める、除外する、または無効にするかを指定するチェックボックスも一緒に表示されます。ユーザーは:optionsキーワード引数により指定された値は、変更できません。

:optionsキーワードにたいする引数は、alist内の適切なキーにたいする仕様のリストであるべきです。これらは通常、単純なアトムであり、それらは自身をを意味します。たとえば:

:options '("foo" "bar" "baz")

specifies that there are three known keys, namely "foo", "bar" and "baz", which will always be shown first.

たとえば"bar"キーに対応する値を整数だけにするというように、特定のキーに対して値の型を制限したいときがあるかもしれません。これはリスト内でアトムのかわりにリストを使用することにより、指定することができます。前述のように、１つ目の要素はそのキーを指定し、２つ目の要素は値の型を指定します。たとえば:

:options '("foo" ("bar" integer) "baz")

最後に、キーが表示される方法を変更したいときもあるかもしれません。デフォルトでは、:optionsキーワードで指定された特別なキーはユーザーが変更できないので、キーは単にconstとして表示されます。しかし、たとえばそれが関数バインディングをもつシンボルだと知っている場合はfunction-itemといったように、あるキーの表示のために、より特化した型を使用したいと思うかもしれません。これは、キーに対してシンボルを使うかわりに、カスタマイズ型指定を使用することにより、行うことができます。

:options '("foo"
           ((function-item some-function) integer)
           "baz")

多くのalistは、コンスセルのかわりに２要素のリストを使用します。たとえば、

(defcustom cons-alist
  '(("foo" . 1) ("bar" . 2) ("baz" . 3))
  "Each element is a cons-cell (KEY . VALUE).")

のかわりに以下を使用します

(defcustom list-alist
  '(("foo" 1) ("bar" 2) ("baz" 3))
  "Each element is a list of the form (KEY VALUE).")

リストはコンスセルの最上位に実装されているため、上記のlist-alistを、コンスセルのalist(value-typeが実際の値を含む１要素のリストであるような)として扱うことができます。

(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
  "Each element is a list of the form (KEY VALUE)."
  :type '(alist :value-type (group integer)))

listのかわりにgroupを使用するのは、その目的に適したフォーマットのためだけです。

同様に、以下のようなトリックの類を用いることにより、より多くの値が各キー連づけられたalistを得ることができます:

(defcustom person-data '(("brian"  50 t)
                         ("dorith" 55 nil)
                         ("ken"    52 t))
  "Alist of basic info about people.
Each element has the form (NAME AGE MALE-FLAG)."
  :type '(alist :value-type (group integer boolean)))

(plist :key-type key-type :value-type value-type)

このカスタマイズ型はalist(上位参照)と似ていますが、(1)情報がプロパティーリスト(プロパティリストを参照してください)に格納され、(2)key-typeが省略された場合、デフォルトはsexpではなく、symbolになります。

(choice alternative-types…)

値はalternative-typesのうちの1つに適合しなければなりません。たとえば、(choice integer string)では整数か文字列が許されます。

カスタマイズバッファーでは、ユーザーはメニューを使用して候補を選択して、それらの候補にたいして通常の方法で値を編集できます。

通常この選択からメニューの文字列が自動的に決定されます。しかし候補の中に:tagキーワードを含めることにより、メニューにたいして異なる文字列を指定できます。たとえば、空白の数を意味する整数と、その通りに使用したいテキストにたいする文字列の場合は、以下のような方法でカスタマイズ型を記述したいかもしれません

(choice (integer :tag "Number of spaces")
        (string :tag "Literal text"))

この場合メニューは、‘Number of spaces’と‘Literal text’を提示します。

const以外のnilが有効な値ではない候補には、:valueキーワードを使用して、有効なデフォルト値を指定するべきです。型キーワードを参照してください。

複数の候補によりいくつかの値が提供される場合、カスタマイズは適合する値をもつ最初の候補を選択します。これは常に、もっとも特有な型を最初に、もっとも一般的な型を最後にリストすべきことを意味します。以下は適切な使い方の例です:

(choice (const :tag "Off" nil)
        symbol (sexp :tag "Other"))

この使い方では、特別な値nilはその他のシンボルとは別に扱われ、シンボルは他のLisp式とは別に扱われます。

(radio element-types…)

This is similar to choice, except that the choices are displayed using radio buttons rather than a menu. This has the advantage of displaying documentation for the choices when applicable and so is often a good choice for a choice between constant functions (function-item customization types).

(const value)

値はvalueでなければならず、他は許されません。

constは主にchoiceの中で使用されます。たとえば、(choice integer (const nil))では、整数かnilが選択できます。

choiceの中では、:tagとともにconstが使用される場合があります。たとえば、

(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (const :tag "Ask" foo))

これはtがyes、nilがno、fooが“ask”を意味することを示します。

(other value)

この候補は任意のLisp値にマッチできますが、ユーザーがこの候補を選択した場合は、値valueが選択されます。

otherは主にchoiceの最後の要素に使用されます。たとえば、

(choice (const :tag "Yes" t)
        (const :tag "No" nil)
        (other :tag "Ask" foo))

これはtがyes、nilがno、それ以外は“ask”を意味することを示します。ユーザーが候補メニューから‘Ask’を選択した場合は、値fooが指定されます。しかし、その他の値(t、nil、fooを除く)では、fooと同様に‘Ask’が表示されます。

(function-item function)

constと同様ですが、値が関数のときに使用されます。これはドキュメント文字列も関数名と同じように表示します。ドキュメント文字列は、:docで指定した文字列か、function自身のドキュメント文字列です。

(variable-item variable)

constと同様ですが、値が変数名のときに使用されます。これはドキュメント文字列も変数名と同じように表示します。ドキュメント文字列は、:docで指定した文字列か、variable自身のドキュメント文字列です。

(set types…)

値はリストでなければならず、指定されたtypesの1つにマッチしなければなりません。

これはカスタマイズバッファーではチェックリストとして表示されるので、typesはそれぞれ対応する要素を1つ、あるいは要素をもちません。同じ1つのtypesにマッチするような、異なる2つの要素を指定することはできません。たとえば、(set integer symbol)は、リスト内で1つの整数、および/または1つのシンボルが許され、複数の整数や複数のシンボルは許されません。結果として、set内でintegerのような特定的ではない型を使用するのは稀です。

以下のように、const型はset内のtypesでよく使用されます:

(set (const :bold) (const :italic))

alist内で利用できる要素を示すために使用されることもあります:

(set (cons :tag "Height" (const height) integer)
     (cons :tag "Width" (const width) integer))

これによりユーザーにオプションでheightとwidthの値を指定させることができます。

(repeat element-type)

値はリストでなければならず、リストの各要素は型element-typeに適合しなければなりません。カスタマイズバッファーでは要素のリストとして表示され、‘[INS]’および‘[DEL]’ボタンにより、要素の追加や削除が行われます。

(restricted-sexp :match-alternatives criteria)

これはもっとも汎用的な複合型の構築方法です。値はcriteriaを満足する任意のLispオブジェクトです。criteriaはリストで、リストの各要素は以下のうちの1つを満たす必要があります:

述語 — つまり、副作用をもたず引数は1つ、その引数に応じてnilか非nilのどちらかをリターンする関数。リスト内での述語の使用により、その述語が非nilをリターンするようなオブジェクトが許されることを意味する。
クォートされた定数 — つまり、'object。リスト内でこの要素は、object自身が容認される値であることを示す。

たとえば、

(restricted-sexp :match-alternatives
                 (integerp 't 'nil))

これは整数、t、nilを正当な値として受け入れます。

カスタマイズバッファーは適切な値をそれらの入力構文ですべて表示し、ユーザーはこれらをテキストとして編集できます。

以下は複合型でキーワード/値ペアーとして使用できるキーワードのテーブルです:

:tag tag: tagは、ユーザーとのコミュニケーションのために、その候補の名前として使用される。choice内に出現する型にたいして有用。
:match-alternatives criteria: criteriaは可能な値とのマッチに使用されます。restricted-sexp内でのみ有用です。
:args argument-list: 型構築の引数としてargument-listの要素を使用します。たとえば、(const :args (foo))は(const foo)と等価です。明示的に:argsとく記述する必要があるのは稀です。なぜなら、最後のキーワード/値ペアーの後に続くものは何であれ、引数として認識されるからです。

15.4.3 リストへのスプライス

:inline機能により、可変個の要素を、カスタマイズ型のlistやvectorの途中にスプライス(splice: 継ぎ足す)することができます。listやvector記述を含む型にたいして:inline tを追加することによりこれを使用します。

通常listやvector型の仕様は、単一の要素型を表します。しかしエントリーが:inline tを含む場合、マッチする値は、その含まれたシーケンスに直接マージされます。たとえば、エントリーが3要素のリストにマッチする場合、全体が3要素のシーケンスになります。これはバッククォート構文(バッククォートを参照)の‘,@’に類似しています。

たとえば、最初の要素がbazで、残りの引数は0個以上のfooかbarでなければならないリストを指定する場合は、以下のカスタマイズ型を使用します:

(list (const baz) (set :inline t (const foo) (const bar)))

これは (baz)、(baz foo)、(baz bar)、(baz foo bar)のような値にマッチします。

要素の型がchoiceの場合は、choice自身の中で:inlineを使用せずに、choiceの候補(の一部)の中で使用します。たとえば、最初がファイル名で開始され、その後にシンボルtか2つの文字列を続けなければならないリストにマッチさせるには、以下のカスタマイズ型を使用します:

(list file
      (choice (const t)
              (list :inline t string string)))

選択においてユーザーが選択肢の1つ目を選んだ場合、リスト全体が2つの要素をもち、2つ目の要素はtになります。ユーザーが2つ目の候補を選んだ場合、リスト全体が3つの要素をもち、2つ目と3つ目の要素は文字列でなければなりません。

15.4.4 型キーワード

カスタマイズ型内の型名シンボルの後にキーワード/引数ペアーを指定できます。以下は使用できるキーワードと、それらの意味です:

:value default

デフォルト値を提供する。

その候補にたいしてnilが有効な値でない場合は、:valueに有効なデフォルトを指定することが必須になります。

choiceの内部の候補として出現する型にたいしてこれを使用する場合、ユーザーがカスタマイズバッファー内のメニューによりこの候補を選択したときに、使用するデフォルト値を最初に指定します。

もちろんオプションの実際の値がこの候補に適合する場合は、defaultではなく実際の値が表示されます。

:format format-string

この文字列は、その型に対応する値を説明するために、バッファーに挿入されます。format-string内では、以下の‘%’エスケープが利用できます:

‘%[button%]’

ボタンとしてマークされたテキストbuttonを表示する。:action属性は、ユーザーがそれを呼び出したときに、そのボタンが何を行うか指定する。この属性の値は２つの引数 — ボタンが表示されるのでウィジェットとイベント — をとる関数。

異なるアクションを行う2つの異なるボタンを指定する方法はない。

‘%{sample%}’

:sample-faceにより指定された、スペシャルフェイス内のsampleを表示する。

‘%v’

そのアイテムの値を代替えする。その値がどのように表示されるかはアイテムの種類と、(カスタマイズ型にたいしては)カスタマイズ型にに依存する。

‘%d’

そのアイテムのドキュメント文字列を代替えする。

‘%h’

‘%d’と同様ふぁが、ドキュメント文字列が複数行の場合に、ドキュメント文字列全体か最初の行だけかを制御するボタンを追加する。

‘%t’

その位置でタグに置き換える。:tagキーワードでタグを指定する。

‘%%’

リテラル‘%’を表示する。

:action action

ユーザーがボタンをクリックした場合はactionを実行します。

:button-face face

‘%[…%]’で表示されたボタンテキストにたいして、フェイスface(フェイス名、またはフェイス名のリスト)を使用します。

:button-prefix prefix

:button-suffix suffix

これらはボタンの前、または後に表示されるテキストを指定します。以下が指定できます:

nil: テキストは挿入されない。
文字列: その文字列がリテラルに挿入される。
シンボル: そのシンボルの値が使用される。

:tag tag

この型に対応する値(または値の一部)にたいするタグとしてtag(文字列)を使用する。

:doc doc

この型に対応する値(または値の一部)にたいするドキュメント文字列としてdocを使用する。これが機能するためには、:formatにたいする値を指定し、その値にたいして‘%d’か‘%h’を使用しなければならない。

ある型にたいしてドキュメント文字列を指定するのは、:choice内の候補の型や、他の複合型の一部について情報を提供するのが通常の理由である。

:help-echo motion-doc

widget-forwardやwidget-backwardでこのアイテムに移動したときに、エコーエリアに文字列motion-docを表示する。さらに、マウスのhelp-echo文字列としてmotion-docが使用され、これは実際にはヘルプ文字列を生成するために評価される関数またはフォームかもしれない。もし関数の場合、これは1つの引数(そのウィジェット)で呼び出される。

:match function

値がその型にマッチするか判断する方法を指定する。対応する値functionは、2つの引数(ウィジェットと値)をとる関数で、値が適切なら非nilをリターンすること。

:validate function

入力にたいして検証を行う関数を指定する。functionは引数としてウィジェットをとり、そのウィジェットのカレント値がウィジェットにたいして有効ならnilをリターンすること。それ以外は無効なデータを含むウィジェットをリターンして、そのウィジェットの:errorプロパティに、そのエラーを説明する文字列をセットすること。

15.4.5 新たな型の定義

前のセクションでは、defcustomにたいして型の詳細な仕様を作成する方法を説明しました。そのような型仕様に名前を与えたい場合があるかもしれません。理解しやすいケースとしては、多くのユーザーオプションに同じ型を使用する場合などです。各オプションにたいして仕様を繰り返すより、その型に名前を与えて、defcustomそれぞれにその名前を使用することができます。他にもユーザーオプションの値が再帰的なデータ構造のケースがあります。あるデータ型がそれ自身を参照できるようにするためには、それが名前をもつ必要があります。

カスタマイズ型はウィジェットとして実装されているめ、新しいカスタマイズ型を定義するには、新たにウィジェット型を定義します。ここではウィジェットインターフェイスの詳細は説明しません。Introduction in The Emacs Widget Libraryを参照してください。　かわりに、シンプルな例を用いて、カスタマイズ型を新たに定義するのに必要となる、最小限の機能について説明します。

(define-widget 'binary-tree-of-string 'lazy
  "A binary tree made of cons-cells and strings."
  :offset 4
  :tag "Node"
  :type '(choice (string :tag "Leaf" :value "")
                 (cons :tag "Interior"
                       :value ("" . "")
                       binary-tree-of-string
                       binary-tree-of-string)))

(defcustom foo-bar ""
  "Sample variable holding a binary tree of strings."
  :type 'binary-tree-of-string)

新しいウィジェットを定義するための関数は、define-widgetと呼ばれます。1つ目の引数は、新たなウィジェット型にしたいシンボルです。2つ目の引数は既存のウィジェットを表すシンボルで、新しいウィジェットではこの既存のウィジェットと異なる部分を定義することになります。新たなカスタマイズ型を定義する目的にたいしては、lazyウィジェットが最適です。なぜならこれは、defcustomにたいするキーワード引数と同じ構文、同じ名前でキーワード引数:typeを受け取るからです。3つ目の引数は、新しいウィジェットにたいするドキュメント文字列です。この文字列は、M-x widget-browse RET binary-tree-of-string RETコマンドで参照することができるようになります。

これらの必須の引数の後にキーワード引数が続きます。もっとも重要なのは:typeで、これはこのウィジェットにマッチさせたいデータ型を表します。上記の例ではbinary-tree-of-stringは文字列、またはcarとcdrがbinary-tree-of-stringであるようなコンスセルです。この定義中でのウィジェット型への参照に注意してください。:tag属性はユーザーインターフェイスでウィジェット名となる文字列、:offset引数はカスタマイズバッファーでのツリー構造の外観で，子ノードと関連する親ノードの間に4つのスペースを確保します。

defcustomは、通常のカスタマイズ型に使用される方法で新しいウィジェットを表示します。

lazyという名前の由来は、他のウィジェットの場合、それらがバッファーでインスタンス化されるとき、他の合成されたウィジェットが下位のウィジェットを内部形式に変換するからです。この変換は再帰的なので、下位のウィジェットは、それら自身の下位ウィジェットへと変換されます。データ構造自体が再帰的な場合、この変換は無限再帰(infinite recursion)となります。lazyウィジェットは、:type引数を必要なときだけ変換することにより、この再帰を防ぎます。

15.5 カスタマイズの適用

以下の関数には、変数とフェイスにたいして、そのユーザーのカスタマイズ設定をインストールる役目があります。それらの関数は、ユーザーがカスタマイズインターフェイスで‘Save for future sessions’を呼び出したときに、次回のEmacs起動時に評価されるようにcustom-set-variablesフォーム、および/またはcustom-set-facesフォームをがカスタムファイルに書き込まれることによって効果をもちます。

Function: custom-set-variables &rest args

この関数はargsにより指定された変数のカスタマイズをインストールします。args内の引数はそれぞれ、以下のようなフォームです

(var expression [now [request [comment]]])

varは変数名(シンボル)、expressionはカスタマイズされた値に評価される式です。

このcustom-set-variables呼び出しより前にvarにたいしてdefcustomフォームが評価された場合は、即座にexpressionが評価され、その変数の値にその結果がセットされます。それ以外は、その変数のsaved-valueプロパティにexpressionが格納され、これに関係するdefcustomが呼び出されたとき(通常はその変数を定義するライブラリーがEmacsにロードされたとき)に評価されます。

now、request、commentエントリーは内部的な使用に限られており、省略されるかもしれません。nowは、もし非nilの場合には、たとえその変数のdefcustomフォームが評価されていなくても、その変数の値がそのときセットされます。requestは即座にロードされる機能のリストです(名前つき機能を参照)。commentはそのカスタマイズを説明する文字列です。

Function: custom-set-faces &rest args

この関数はargsにより指定されたフェイスのカスタマイズをインストールします。args内の引数はそれぞれ、以下のようなフォームです

(face spec [now [comment]])

faceはフェイス名(シンボル)、specはそのフェイスにたいするカスタマイズされたフェイス仕様です(フェイスの定義を参照)。

now、request、commentエントリーは内部的な使用に限られており、省略されるかもしれません。nowは、もし非nilの場合には、たとえdeffaceフォームが評価されていなくても、そのフェイス仕様がそのときセットされます。commentはそのカスタマイズを説明する文字列です。

15.6 カスタムテーマ

カスタムテーマ(Custom themes)とはユニットとして有効または無効にできるセッティングのコレクションです。Custom Themes in The GNU Emacs Manualを参照してくださいカスタムテーマはそれぞれEmacs Lispソースファイルにより定義され、それらはこのセクションで説明する慣習にしたがう必要があります。(カスタムファイルを手で記述するかわりに、カスタマイズ風のインターフェイスを使用して作成することもできます。Creating Custom Themes in The GNU Emacs Manualを参照してください。)

カスタムファイルはfoo-theme.elのように命名すべきです。ここでfooはテーマの名前です。このファイルでの最初のLispフォームはdefthemeの呼び出しで、最後のフォームはprovide-themeにすべきです。

Macro: deftheme theme &optional doc

このマクロはカスタムテーマの名前としてtheme(シンボル)を宣言します。オプション引数docは、そのテーマを説明する文字列であるべきです。この文字列はユーザーがdescribe-themeコマンドを呼び出したり、‘*Custom Themes*’バッファーで?をタイプしたときに表示されます。

Two special theme names are disallowed (using them causes an error): user is a dummy theme that stores the user’s direct customization settings, and changed is a dummy theme that stores changes made outside of the Customize system.

Macro: provide-theme theme: このマクロは完全に仕様が定められたテーマ名themeを宣言します。

defthemeとprovide-themeの違いは、そのテーマセッティングを規定するLispフォーム(通常はcustom-theme-set-variablesの呼び出し、および/またはcustom-theme-set-facesの呼び出し)です。

Function: custom-theme-set-variables theme &rest args

この関数は、カスタムテーマthemeの変数のセッティングを規定します。themeはシンボルです。args内の各引数はフォームのリストです。

(var expression [now [request [comment]]])

ここでリストエントリーはcustom-set-variablesのときと同じ意味をもちます。カスタマイズの適用を参照してください。

Function: custom-theme-set-faces theme &rest args

この関数は、カスタムテーマthemeのフェイスのセッティングを規定します。themeはシンボルです。args内の各引数はフォームのリストです。

(face spec [now [comment]])

ここでリストエントリーはcustom-set-facesのときと同じ意味をもちます。カスタマイズの適用を参照してください。

In theory, a theme file can also contain other Lisp forms, which would be evaluated when loading the theme, but that is bad form. To protect against loading themes containing malicious code, Emacs displays the source file and asks for confirmation from the user before loading any non-built-in theme for the first time. As such, themes are not ordinarily byte-compiled, and source files always take precedence when Emacs is looking for a theme to load.

以下の関数は、テーマをプログラム的に有効または無効にするのに有用です:

Function: custom-theme-p theme: この関数はtheme(シンボル)がカスタムテーマの名前の場合(たとえば、そのテーマが有効かどうかにかかわらず、カスタムテーマがEmacsにロードされていれば)、非nilをリターンします。それ以外はnilをリターンします。

Variable: custom-known-themes: The value of this variable is a list of themes loaded into Emacs. Each theme is represented by a Lisp symbol (the theme name). The default value of this variable is a list containing two dummy themes: (user changed). The changed theme stores settings made before any Custom themes are applied (e.g., variables set outside of Customize). The user theme stores settings the user has customized and saved. Any additional themes declared with the deftheme macro are added to the front of this list.

Command: load-theme theme &optional no-confirm no-enable: この関数はthemeという名前のカスタムテーマを、変数custom-theme-load-pathで指定されたディレクトリーを探して、ソースファイルからロードします。Custom Themes in The GNU Emacs Manualを参照してください。また、そのテーマの変数とフェイスのセッティングが効果を及ぼすようにテーマをenablesにします(オプション引数no-enableが非nilでない場合)さらに、オプション引数no-confirmが非nilでない場合は、そのテーマをロードする前にユーザーに確認を求めます。

Command: enable-theme theme: この関数はthemeという名前のカスタムテーマを有効にします。そのようなテーマがロードされていない場合は、エラーをシグナルします。

Command: disable-theme theme: この関数はthemeという名前のカスタムテーマを無効にします。テーマはロードされたまま残りので、続けてenable-themeを呼び出せばテーマは再び有効になります。

16 ロード

Lispコードのファイルをロードすることは、その内容をLispオブジェクト形式でLisp環境に取り込むことを意味します。Emacsはファイルを探してオープンし、テキストを読み込んで各フォームを評価してから、そのファイルをクローズします。そのようなファイルはLispライブラリー(Lisp library)とも呼ばれます。

eval-buffer関数がバッファー内のすべての式を評価するのと同様に、load関数はファイル内のすべての式を評価します。異なるのはEmacsバッファー内のテキストではなく、load関数はディスク上で見つかったファイル内のテキストを読み込み、評価することです。

ロードされたファイルは、ソースコードかバイトコンパイルされたコードとしてLisp式を含んでいなければなりません。このファイル内の各フォームは、トップレベルフォーム(top-level form)と呼ばれます。ロード可能なファイル内のフォームにたいする特別なフォーマットはありません。ファイル内のフォームはどれも、同じように直接バッファーにタイプされ、そこで評価されるでしょう(実際、ほとんどのコードはこの方法でテストされます)。多くの場合、そのフォームは関数定義と変数定義です。

Emacs can also load compiled dynamic modules: shared libraries that provide additional functionality for use in Emacs Lisp programs, just like a package written in Emacs Lisp would. When a dynamic module is loaded, Emacs calls a specially-named initialization function which the module needs to implement, and which exposes the additional functions and variables to Emacs Lisp programs.

For on-demand loading of external libraries which are known in advance to be required by certain Emacs primitives, see section 動的にロードされるライブラリー.

16.1 プログラムがロードを行う方法		`load`関数、その他。
16.2 ロードでの拡張子		`load`が試みられるサフィックスについての詳細。
16.3 ライブラリー検索		ロードするライブラリーの検索。
16.4 非ASCII文字のロード		Emacs Lispファイル内の非ASCII文字。
16.5 autoload		オートロードのための関数のセットアップ。
16.6 多重ロード		ファイルを2度ロードする場合の配慮。
16.7 名前つき機能		まだロードされていないライブラリーのロード。
16.8 どのファイルで特定のシンボルが定義されているか		特定のシンボルがどのファイルで定義されているかの検索。
16.9 アンロード		How to unload a library that was loaded.
16.10 ロードのためのフック		特定のライブラリーがロードされたとき実行されるコードの提供。
16.11 Emacs Dynamic Modules		Modules provide additional Lisp primitives.

16.1 プログラムがロードを行う方法

Emacs Lispにはロードのためのインターフェイスがいくつかあります。たとえば、autoloadはファイル内で定義された関数にたいしてプレースホルダーとなるオブジェクトを作成します。この関数はオートロードされる関数を呼び出すために、ファイルからその関数の実際の定義の取得を試みます(autoloadを参照)。requireは、ファイルがまだロードされていない場合にファイルをロードします(名前つき機能を参照)。これらすべての関数は、処理を行うために最終的にloadを呼び出します。

Function: load filename &optional missing-ok nomessage nosuffix must-suffix

この関数はLispコードのファイルを見つけてオープンし、その中のすべてのフォームを評価して、そのファイルをクローズします。

To find the file, load first looks for a file named filename.elc, that is, for a file whose name is filename with the extension ‘.elc’ appended. If such a file exists, it is loaded. If there is no file by that name, then load looks for a file named filename.el. If that file exists, it is loaded. If Emacs was compiled with support for dynamic modules (see section Emacs Dynamic Modules), load next looks for a file named filename.ext, where ext is a system-dependent file-name extension of shared libraries. Finally, if neither of those names is found, load looks for a file named filename with nothing appended, and loads it if it exists. (The load function is not clever about looking at filename. In the perverse case of a file named foo.el.el, evaluation of (load "foo.el") will indeed find it.)

If Auto Compression mode is enabled, as it is by default, then if load can not find a file, it searches for a compressed version of the file before trying other file names. It decompresses and loads it if it exists. It looks for compressed versions by appending each of the suffixes in jka-compr-load-suffixes to the file name. The value of this variable must be a list of strings. Its standard value is (".gz").

オプション引数nosuffixが非nilの場合loadはサフィックス‘.elc’と‘.el’を試みません。この場合、ロードしたいファイルの正確な名前を指定しなければなりません。ただしAuto Compressionモードが有効な場合には、loadは圧縮されたバージョンを探すために、jka-compr-load-suffixesを使用します。正確なファイル名の指定と、、nosuffixにたいしてtを使用することにより、foo.el.elのような名前のファイルにたいするロードの試みを抑止できます。

If the optional argument must-suffix is non-nil, then load insists that the file name used must end in either ‘.el’ or ‘.elc’ (possibly extended with a compression suffix) or the shared-library extension, unless it contains an explicit directory name.

If the option load-prefer-newer is non-nil, then when searching suffixes, load selects whichever version of a file (‘.elc’, ‘.el’, etc.) has been modified most recently.

filenameがfooやbaz/foo.barのような相対ファイル名の場合、loadは変数load-pathを使用してそのファイルを探します。これはload-path内にリストされた各ディレクトリーにfilenameを追加して、最初に見つかったら名前のマッチするファイルをロードします。デフォルトディレクトリーを意味するnilがload-pathで措定されたときだけ、カレントデフォルトディレクトリーを試みます。loadはload-path内の最初のディレクトリーで利用可能な3つのサフィックスすべてを試行してから、2つ目のディレクトリーで３つのサフィックスすべてを試行する、というようにファイルを探します。ライブラリー検索を参照してください。

最終的に見つかったファイル、およびEmacsがそのファイルを見つけたディレクトリーが何であれ、Emacsはそのファイル名を変数load-file-nameの値にセットします。

foo.elcがfoo.elより古いと警告された場合、それはfoo.elのリコンパイルを考慮すべきことを意味します。バイトコンパイルを参照してください

(コンパイルされていない)ソースファイルをロードしたとき、Emacsがファイルをvisitしたときと同じようにloadは文字セットの変換を行います。コーディングシステムを参照してください。

コンパイルされていないファイルをロードするとき、Emacsはそのファイルに含まれる任意のマクロ(マクロを参照)を展開します。わたしたちはこれをeagerマクロ展開(eager macro expansion)と呼んでいます。(関連するコードを実行するまで展開を延期するのではなく)これを行うことにより、コンパイルされていないコード実行のスピードが明らかに向上します。このマクロ展開は、循環参照により行うことができないときもあります。これの一番簡単な例は、ロードしようとしているファイルが他のファイルで定義されているマクロを参照しているが、そのファイルはロードしようとしているファイルを必要としている場合です。これは一般的には無害です。Emacsは問題の詳細を与えるために警告(‘Eager macro-expansion skipped due to cycle…’)をプリントしますが、単にその時点ではマクロを展開せずに、そのファイルはロードされます。あなたはこの問題が発生しないように、コードをリストラクチャーしたいと思うかもしれません。コンパイル済みファイルでは、マクロ展開はコンパイル時に行われるので、ロード時のマクロ展開は行われません。マクロとバイトコンパイルを参照してください。

nomessageが非nilでない場合は、ロードの間、エコーエリアに‘Loading foo...’や‘Loading foo...done’のようなメッセージが表示されます。

ファイルをロードする間のハンドルされないエラーは、ロードを終了させます。autoloadのためのロードの場合、ロードの間に定義された任意の関数定義は元に戻されます。

If load can’t find the file to load, then normally it signals a file-error (with ‘Cannot open load file filename’). But if missing-ok is non-nil, then load just returns nil.

式の読み取りにたいしてloadがreadのかわりに使用する関数を指定するために、変数load-read-functionを使用できます。以下を参照してください。

ファイルが正常にロードされた場合、loadはtをリターンします。

Command: load-file filename: このコマンドは、ファイルfilenameをロードします。filenameが相対ファイル名の場合は、カレントデフォルトディレクトリーとみなされます。このコマンドは、load-pathを使用せず、サフィックスの追加もしません。しかし、(Auto Compressionモードが有効な場合は)圧縮されたバージョンの検索を行います。ロードするファイル名を正確に指定したい場合は、このコマンドを使用してください。

Command: load-library library: このコマンドはlibraryという名前のライブラリーをロードします。このコマンドは、引数を読み取る方法がインタラクティブであることを除き、loadと同じです。Lisp Libraries in The GNU Emacs Manualを参照してください。

Variable: load-in-progress: この変数は、Emacsがファイルをロード中のときは非nil、それ以外はnilです。

Variable: load-file-name: このセクションの最初に説明した検索でEmacsがファイルを見つけて、そのファイルをロード中のとき、この変数の値はそのファイルの名前です。

Variable: load-read-function

この変数は、loadとeval-regionが式の読み取るために、readのかわりに使用する関数を指定します。指定する関数はreadと同様、引数が1つの関数です。

By default, this variable’s value is read. See section 入力関数.

この変数を使用するかわりに、別の新たな方法を使用するほうが明確です。eval-regionのread-function引数に、その関数を渡す方法です。Evalを参照してください。

Emacsのビルドでloadがどのように使用されているかについての情報は、Emacsのビルドを参照してください。

16.2 ロードでの拡張子

ここでは、loadが試行するサフィックスについて、技術的な詳細を説明します。

Variable: load-suffixes: これは(ソースまたはコンパイル済みの)Emacs Lispファイルを示すサフィックスのリストです。空の文字列が含まれるべきではありません。loadは、指定されたファイル名にLispファイルのサフィックスを追加するときに、これらのサフィックスを使用します。標準的な値は(".elc" ".el")で、これは前のセクションで説明した振る舞いとなります。

Variable: load-file-rep-suffixes

これは同じファイルにたいする異なる表現を示すサフィックスのリストです。このリストは空の文字列から開始されるべきです。loadはファイルを検索するときは、他のファイルを検索する前にこのリストのサフィックスを順番にファイル名に追加します。

Auto Compressionモードを有効にすることによりjka-compr-load-suffixesのサフィックスがこのリストに追加され、無効にすると再びリストから取り除かれます。load-file-rep-suffixesの標準的な値は、Auto Compressionモードが無効な場合は("")です。jka-compr-load-suffixesの標準的な値が(".gz")であることを考慮すると、Auto Compressionモードが有効な場合のload-file-rep-suffixesの標準的な値は("" ".gz")です。

Function: get-load-suffixes: この関数は、must-suffix引数が非nilのときは、loadが試みるべきすべてのサフィックスを順番にしたがったリストでリターンします。この関数はload-suffixesとload-file-rep-suffixesの両方を考慮に入れます。load-suffixes、jka-compr-load-suffixes、load-file-rep-suffixesがすべて標準的な値の場合、この関数はAuto Compressionモードが有効なら(".elc" ".elc.gz" ".el" ".el.gz")、無効なら(".elc" ".el")をリターンします。

まとめると、loadは通常まず(get-load-suffixes)の値のサフィックスを試み、つぎにload-file-rep-suffixesを試みます。nosuffixが非nilの場合は前者がスキップされ、must-suffixが非nilの場合は後者がスキップされます。

User Option: load-prefer-newer: このオプションが非nilの場合は、ファイルが見つかった最初のサフィックスで停止せずに、loadはすべてのサフィックスをテストして、一番新しいファイルを使用します。

16.3 ライブラリー検索

EmacsがLispライブラリーをロードするときは、変数load-path.<により指定されるディレクトリー内のライブラリーを検索します。

Variable: load-path: The value of this variable is a list of directories to search when loading files with load. Each element is a string (which must be a directory) or nil (which stands for the current working directory).

Emacsは起動時にいくつかのステップによりload-pathの値をセットアップします。最初に、Emacsがコンパイルされたときのデフォルトロケーションセット(default locations set)を使用して、load-pathを初期化します。通常これは以下のようなディレクトリーです

"/usr/local/share/emacs/version/lisp"

(以下の例では、あなたがインストールしたEmacsのインストールプレフィクスに合うように/usr/localを置き換えてください。)これらのディレクトリーには、Emacsとともにインストールされた、標準的なLispファイルが含まれます。Emacsがこれらを見つけられない場合は、正常に起動しないでしょう。

Emacsをビルドしたディレクトリーから起動した場合 −−− つまり正式にインストールされた実行形式ではないEmacsを起動した場合 —　、Emacsはビルドされたディレクトリーのソースのlispディレクトリーを使用してload-pathを初期化します。ソースとは別のディレクトリーでEmacsをビルドした場合は、ビルドしたディレクトリーのlispディレクトリーも追加します。(どちらの場合も、要素は絶対ファイル名になります。)

--no-site-lispオプションでEmacsを起動した場合を除き、load-pathの先頭に2つのさらにsite-lispを追加します。これらはローカルにインストールされたLispファイで、通常は:

"/usr/local/share/emacs/version/site-lisp"

と

"/usr/local/share/emacs/site-lisp"

の形式です。1つ目は特定のバージョンのEmacsにたいしてローカルにインストールされたものです。2つ目はインストールされたすべてのバージョンのEmacsが使用することを意図してローカルにインストールされたものです。(インストールされたものでないEmacsが実行された場合は、もし存在すればソースディレクトリーとビルドディレクトリーのsite-lispディレクトリーも追加します。これらのディレクトリーは通常、site-lispディレクトリーを含みません。)

環境変数EMACSLOADPATHがセットされている場合は、上述の初期化プロセスが変更されます。Emacsは、この環境変数の値にもとづいてload-pathを初期化します。

The syntax of EMACSLOADPATH is the same as used for PATH; directories are separated by ‘:’ (or ‘;’, on some operating systems). 以下は、(shスタイルのシェルから)EMACSLOADPATH変数をセットする例です:

export EMACSLOADPATH=/home/foo/.emacs.d/lisp:

環境変数の値内の空の要素は、(上記例のような)末尾、先頭、中間にあるかに関わらず、標準の初期化処理により決定されるload-pathのデフォルト値に置き換えられます。そのような空要素が存在しない場合には、EMACSLOADPATHによりload-path全体が指定されます。空要素、または標準のLispファイルを含むディレクトリーへの明示的なパスのどちらかを含めなければなりません。さもないとEmacsが関数を見つけられなくなります。(load-pathを変更する他の方法は、Emacs起動時にコマンドラインオプション-Lを使用する方法です。以下参照。)

load-path内の各ディレクトリーにたいし、Emacsはそのディレクトリーがファイルsubdirs.elを含むか確認し、もしあればそれをロードします。subdirs.elファイルは、load-pathのディレクトリーみたいして任意のサブディレクトリーを追加するためのコードが含まれており、Emacsがビルド/インストールされたとき作成されます。サブディレクトリーと複数階層下のレベルのサブディレクトリーの両方が、直接追加されます。ただし、名前の最初が英数字でないディレクトリー、名前がRCSまたはCVSのディレクトリー、名前が.nosearchというファイルを含むディレクトリーは除外されます。

Emacsは次に、コマンドラインオプション-L(Action Arguments in The GNU Emacs Manualを参照)で指定したロードディレクトリーを追加します。もしあれば、オプションパッケージ(パッケージ化の基礎を参照)がインストールされた場所も追加します。

initファイル(initファイルを参照)で、load-pathに1つ以上のディレクトリーを追加するコードを記述するのは一般的に行なわれています。たとえば:

(push "~/.emacs.d/lisp" load-path)

Emacsのダンプには、load-pathの特別な値を使用します。ダンプされたEmacsをカスタマイズするためにsite-load.elまたはsite-init.elを使用する場合、これらのファイルが行ったload-pathにたいする変更はすべて、ダンプ後失われます。

Command: locate-library library &optional nosuffix path interactive-call

このコマンドは、ライブラリーlibraryの正確なファイル名を探します。loadと同じ方法でライブラリーを検索し、引数nosuffixもloadの場合と同じ意味です。libraryに指定する名前には、サフィックス‘.elc’または‘.el’を追加しないでください。

pathが非nilの場合は、load-pathのかわりにディレクトリーのリストが使用されます。

locate-libraryがプログラムから呼び出されたときは、ファイル名を文字列としてリターンします。ユーザーがインタラクティブにlocate-libraryを実行したときは、引数interactive-callがtとなり、これはlocate-libraryにたいしてファイル名をエコーエリアに表示するよう指示します。

Command: list-load-path-shadows &optional stringp

このコマンドは、シャドー(shadowed)されたEmacs Lispファイルを表示します。シャドーされたファイルとは、load-pathのディレクトリーに存在するにも関わらず、load-pathのディレクトリーリスト内で前の位置にある他のディレクトリーに同じ名前のファイルが存在するため、通常はロードされないファイルのことです。

たとえば、以下のようにload-pathがセットされていたとします

  ("/opt/emacs/site-lisp" "/usr/share/emacs/23.3/lisp")

そして、両方のディレクトリーにfoo.elという名前のファイルがあるとします。この場合、(require 'foo)は決して2つ目のディレクトリーのファイルをロードしません。このような状況は、Emacsがインストールされた方法に問題があることを示唆します。

Lispから呼び出された場合、この関数はバッファー内に表示するかわりに、シャドーされたファイルリストのメッセージをプリントします。オプション引数stringpが非nilの場合は、かわりにシャドーされたファイルを文字列としてリターンします。

16.4 非ASCII文字のロード

Emacs Lispプログラムが非ASCII文字の文字列定数を含むとき、Emacsではそれらをユニバイト文字列またはマルチバイト文字列のどちらかで表現される場合があります。どちらの表現が使用されるかは、そのファイルがどのようにEmacsに読み込まれたかに依存します。マルチバイト表現へのデコーディングとともに読み込まれた場合、Lispプログラム内のテキストはマルチバイトのテキストとなり、ファイル内の文字列定数はマルチバイト文字列になります。(たとえば)Latin-1文字を含むファイルをデコーディングなしで読み込んだ場合、そのプログラムのテキストはユニバイトのテキストとなり、ファイル内の文字列定数はユニバイト文字列になります。コーディングシステムを参照してください。

マルチバイト文字列がユニバイトバッファーに挿入されるときは自動的にユニバイトに変換されるため、大部分のEmacs Lispプログラムにおいて、マルチバイト文字列が非ASCII文字列であるという事実を意識させないようにすべきです。しかしこれが行われことにより違いが生じる場合には、ローカル変数セクションに‘coding: raw-text’と記述することにより、特定のLispファイルを強制的にユニバイトとして解釈させることができます。この識別子により、そのファイルは無条件でユニバイトとして解釈されます。これは、?vliteralで記述された非ASCII文字にキーバインドするとき重要になります。

16.5 autoload

オートロード(autoload: 自動ロード)の機能により、定義されているファイルをロードすることなく、関数やマクロの存在を登録できます。関数の最初の呼び出しで、実際の定義およびその他の関連するコードをインストールするために適切なライブラリーを自動的にロードし、すべてがすでにロードされていたかのように、実際の定義を実行します。関数やマクロのドキュメントを参照することによっても、オートロードが発生します(ドキュメントの基礎を参照)。

There are two ways to set up an autoloaded function: by calling autoload, and by writing a “magic” comment in the source before the real definition. autoload is the low-level primitive for autoloading; any Lisp program can call autoload at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command update-file-autoloads, which constructs calls to autoload and arranges to execute them when Emacs is built.

Function: autoload function filename &optional docstring interactive type

この関数は、filenameから自動的にロードされるように、functionという名前の関数(またはマクロ)を定義します。文字列filenameのは、functionの実際の定義を取得するファイルを指定します。

filenameがディレクトリー名とサフィックス.elと.elcのどちらも含まない場合、この関数はこれらの強制的にサフィックスを追加します。つまりサフィックスが追加されないただのfilenameという名前のファイルはロードされません。(変数load-suffixesにより要求される正確なサフィックスが指定されます。)

引数docstringは、その関数のドキュメント文字列です。autoloadの呼び出しでドキュメント文字列を指定することにより、その関数の実際の定義をロードせずにドキュメントを見ることが可能になります。この引数の値は通常、関数定義のドキュメント文字列と等しくあるべきです。もし等しくない場合は、その関数のドキュメント文字列がロード時に有効になります。

interactiveが非nilの場合、その関数はインタラクティブに呼び出すことが可能になります。これにより、functionの実際の定義をロードせずに、M-xによる補完が機能するようになります。。ここでは、完全なインタラクティブ指定は与えられません。完全な指定はユーザーが実際にfunctionを呼び出すまで必要ありません。実際にユーザーが呼び出したときに、実際の定義がロードされます。

普通の関数と同様、マクロおよびキーマップをオートロードできます。functionが実際にはマクロの場合はtypeにmacroを指定し、キーマップの場合にはtypeにkeymapを指定します。Emacsのさまざまな部分は、実際の定義をロードせずに、これらの情報を知る必要があるのです。

オートロードされたキーマップは、あるプレフィクスキーがシンボルfunctionにバインドされているときにキーを探す間に、自動的にロードされます。そのキーマップにたいする他の類のアクセスでは、オートロードは発生しません。特に、Lispプログラムが変数の値からそのキーマップを取得してdefine-keyを呼び出した場合には、たとえその変数の名前がシンボルfunctionと同じであっても、オートロードは起こりません。

functionが非voidのオートロードされたオブジェクトではない関数定義をもつ場合、その関数は何も行わずnilをリターンします。それ以外は、オートロードされたオブジェクト(autoload型を参照)を作成して、それをfunctionにたいする関数定義として格納します。オートロードされたオブジェクトは、以下の形式をもちます:

(autoload filename docstring interactive type)

たとえば、

(symbol-function 'run-prolog)
     ⇒ (autoload "prolog" 169681 t nil)

このような場合、"prolog"はロードするファイルの名前、169681はemacs/etc/DOCファイル(ドキュメントの基礎を参照)内のドキュメント文字列への参照で、tはその関数がインタラクティブであり、nilはそれがマクロやキーマップでないことを意味します。

Function: autoloadp object

この関数は、objectがオートロードされたオブジェクトの場合、非nilをリターンします。たとえば、run-prologがオートロードされたオブジェクトかチェックするには、以下を評価します

(autoloadp (symbol-function 'run-prolog))

オートロードされたファイルは、通常は他の定義を含み、1つ以上の機能を必要あるいは提供するかもしれません。(内容の評価でのエラーにより)そのファイルが完全にロードされていない場合、そのロードの間に行われた関数定義やprovideの呼び出しはアンドゥされます。これは、このファイルからオートロードされる関数にたいして再度呼び出しを試みたときに、そのファイルを確実に再ロードさせるためです。このようにしないと、そのファイル内のいくつかの関数はアボートしたロードにより定義されていて、それらはロードされなかった修正後のファイルで提供される正しいサブルーチンを欠くため、正しく機能しないからです。

オートロードされたファイルが意図したLisp関数、またはマクロの定義に失敗した場合には、データ"Autoloading failed to define function function-name"とともにエラーがシグナルされます。

オートロードのマジックコメント(autoload cookieとも呼ばれる)は、オートロード可能なソースファイル内の実際の定義の直前にある、‘;;;###autoload’だけの行から構成されます。コマンドM-x update-file-autoloadsは、対応するautoload呼び出しをloaddefs.el内に書き込みます。(autoload cookieとなる文字列と、update-file-autoloadsにより生成されるファイルの名前は、上述のデフォルトから変更可能です。以下を参照。) Emacsのビルドではloaddefs.elをロードするためにautoloadを呼び出します。M-x update-directory-autoloadsは、より強力です。このコマンドはカレントディレクトリー内のすべてのファイルにたいするオートロードを更新します。

このマジックコメントは、任意の種類のフォームを、loaddefs.el内にコピーできます。このマジックコメントに続くフォームは、そのままコピーされます。しかしオートロード機能が特別に処理するフォームの場合は除外されます(たとえばautoload内への変換)。以下は、そのままコピーされないフォームです:

関数、または関数のようなオブジェクトにたいする定義:: defunとdefmacro。cl-defunとcl-defmacro(Argument Lists in Common Lisp Extensionsを参照)、およびdefine-overloadable-function (mode-local.el内のコメントを参照)も該当
メジャーモードおよびマイナーモードにたいする定義:: define-minor-mode、define-globalized-minor-mode、define-generic-mode、define-derived-mode、easy-mmode-define-minor-mode、easy-mmode-define-global-mode、define-compilation-mode、define-global-minor-mode。
その他のタイプの定義:: defcustom, defgroup, defclass (see EIEIO in EIEIO), and define-skeleton (see Autotyping in Autotyping).

ビルド時に、そのファイル自身をロードするときにフォームを実行しないように、マジックコメントを使用することもできます。これを行なうには、マジックコメントと同じ行にフォームを記述します。これはコメントなので、ソースファイルをロードするとき何も行いません。ただしM-x update-file-autoloadsは、Emacsビルド時に実行されたものは、M-x update-file-autoloadsにコピーします。

以下は、マジックコメントによるオートロードのためにdoctorを準備する例です:

;;;###autoload
(defun doctor ()
  "Switch to *doctor* buffer and start giving psychotherapy."
  (interactive)
  (switch-to-buffer "*doctor*")
  (doctor-mode))

これにより、以下がloaddefs.el内に書き込まれます:

(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.

\(fn)" t nil)

ダブルクォートの直後のバックスラッシュまたは改行は、loaddefs.elのようなプリロードされた未コンパイルだけに使用される慣習です。これは、make-docfileにたいして、ドキュメント文字列をetc/DOCファイルに配するよう指示します。Emacsのビルドを参照してください。また、lib-src/make-docfile.c内のコメントも参照してください。ドキュメント文字列の使い方(usage part)の中の‘(fn)’は、種々のヘルプ関数(ヘルプ関数を参照)が表示するとき、その関数の名前に置き換えられます。

関数定義手法として既知ではなく、認められてもいないような、通常とは異なるマクロにより関数定義を記述した場合、通常のオートロードのマジックコメントの使用により、定義全体がloaddefs.el内にコピーされるでしょう。これは期待した動作ではありません。かわりに以下を記述することにより、意図したautoload呼び出しをloaddefs.el内に配することができます。

;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
  ...)

autoload cookieとして、デフォルト以外の文字列を使用して、デフォルトのloaddefs.elとは異なるファイル内に、対応するオートロード呼び出しを記述できます。これを制御するために、Emacsは2つの変数を提供します:

Variable: generate-autoload-cookie: この変数の値は、Lispコメントの文法に準じた文字列です。M-x update-file-autoloadsは、そのcookieの後のLispフォームを、cookieが生成したオートロードファイル内にコピーします。この変数のデフォルト値は、";;;###autoload"です。

Variable: generated-autoload-file: The value of this variable names an Emacs Lisp file where the autoload calls should go. The default value is loaddefs.el, but you can override that, e.g., in the local variables section of a .el file (see section ファイルローカル変数). The autoload file is assumed to contain a trailer starting with a formfeed character.

以下の関数は、オートロードオブジェクトにより指定されたライブラリーを明示的にロードするために使用されるかもしれません:

Function: autoload-do-load autoload &optional name macro-only: この関数はオートロードオブジェクトautoloadにより指定されたロードを処理します。オプション引数nameに非nilを指定する場合は、関数値がautoloadとなるシンボルを指定します。この場合、この関数のリターン値は、そのシンボルの新しい関数値になります。オプション引数macro-onlyの値がmacroの場合、この関数は関数ではなくマクロのロードだけを有効にします。

16.5.1 When to Use Autoload

Do not add an autoload comment unless it is really necessary. Autoloading code means it is always globally visible. Once an item is autoloaded, there is no compatible way to transition back to it not being autoloaded (after people become accustomed to being able to use it without an explicit load).

The most common items to autoload are the interactive entry points to a library. For example, if python.el is a library defining a major-mode for editing Python code, autoload the definition of the python-mode function, so that people can simply use M-x python-mode to load the library.
Variables usually don’t need to be autoloaded. An exception is if the variable on its own is generally useful without the whole defining library being loaded. (An example of this might be something like find-exec-terminator.)
Don’t autoload a user option just so that a user can set it.
Never add an autoload comment to silence a compiler warning in another file. In the file that produces the warning, use (defvar foo) to silence an undefined variable warning, and declare-function (see section コンパイラーへの定義済み関数の指示) to silence an undefined function warning; or require the relevant library; or use an explicit autoload statement.

16.6 多重ロード

1つのEmacsセッション内で、ファイルを複数回ロードできます。たとえば、バッファーで関数定義を編集して再インストールした後に、元のバージョンに戻したいときがあるかもしれません。これは、元のファイルをリロードすることにより行なうことができます。

ファイルをロードまたはリロードするとき、loadおよびload-library関数は未コンパイルのファイルではなく、バイトコンパイルされた同名のファイルを自動的にロードすることに留意してください。ファイルを再記述して保存後に再インストールする場合には、新しいバージョンをバイトコンパイルする必要があります。さもないと、Emacsは新しいソースではなく、古いバイトコンパイルされたファイルをロードしてしまうでしょう! その場合には、ファイルロード時に表示されるメッセージに、そのファイルのリコンパイルを促す‘(compiled; note, source is newer)’というメッセージが含まれます。

Lispライブラリーファイル内にフォームを記述するときは、そのファイルが複数回ロードされるかもしれないことに留意してください。たとえば、そのライブラリーをリロードするときには、各変数が最初期化されるべきかどうか考慮してください。。変数がすでに初期化されている場合、defvarはその変数の値を変更しません(グローバル変数の定義を参照)。

alistに要素を追加するもっともシンプルな方法は、以下のようなものでしょう:

(push '(leif-mode " Leif") minor-mode-alist)

しかし、これはそのライブラリーがリロードされた場合は、複数の要素を追加してしまうでしょう。この問題を避けるには、add-to-list(リスト変数の変更を参照)を使用します:

(add-to-list 'minor-mode-alist '(leif-mode " Leif"))

時には、ライブラリーが既にロード済みか、明示的にテストしたいときがあるでしょう。そのライブラリーがprovideを使用して名前付きフィーチャ(named feature)を提供する場合は、featurepを使用して前にprovideが実行されているかテストすることができます。かわりに、以下のようにすることもできます:

(defvar foo-was-loaded nil)

(unless foo-was-loaded
  execute-first-time-only
  (setq foo-was-loaded t))

16.7 名前つき機能

provideとrequireは、autoloadにかわるファイルを自動的にロードする関数です。これらは名前付きのフィーチャ(feature: 機能)という面で機能します。オートロードは特定の関数の呼び出しをトリガーにしますが、フィーチャーは最初は他のプログラムが名前により問い合わせたときにロードされます。

フィーチャ名とは、関数、変数などのコレクションを表すシンボルです。これらを定義するファイルは、そのフィーチャをプロバイド(provide: 提供)すべきです。これらのフィーチャを使用する他のプログラムは、その機能をリクワイア(require: 要求)することにより、それらが定義されているか確認できるでしょう。これは、定義がまだロードされていなければ、定義ファイルをロードします。

フィーチャをリクワイアするには、フィーチャ名を引数としてrequireを呼び出します。requireは、意図する機能がすでにプロバイドされているか確認するために、グローバル変数featuresを調べます。もしプロバイドされていなければ、適切なファイルからそのフィーチャをロードします。このファイルは、そのフィーチャをfeaturesに追加するために、トップレベルでprovideを呼び出すべきです。これに失敗すると、requireはエラーをシグナルします。

たとえば、idlwave.el内のidlwave-complete-filenameにたいする定義には、以下のコードが含まれます:

(defun idlwave-complete-filename ()
  "Use the comint stuff to complete a file name."
   (require 'comint)
   (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%={}\\-")
          (comint-completion-addsuffix nil)
          ...)
       (comint-dynamic-complete-filename)))

式(require 'comint)は、comint.elがまだロードされていなければ、comint-dynamic-complete-filenameが確実に定義されるように、そのファイルをロードします。フィーチャは通常、それらを提供するファイルにしたがって命名されるため、requireにファイル名を与える必要はありません。(require命令文がletのボディーの外側にあるのが重要なことに注意してください。変数がletバインドされているライブラリーをロードすることにより、意図せぬ結果、つまりletをexitした後にその変数がアンバインドされます。)

comint.elには以下のトップレベル式が含まれます:

(provide 'comint)

これはcomintはグローバルなリストfeaturesに追加するので、(require 'comint)は今後何も行う必要がないことを知ることができます。

ファイルのトップレベルrequireが使用されたときは、それをロードしたときと同様、そのファイルをバイトコンパイル(バイトコンパイルを参照)したときにも効果が表れます。これはリクワイアされたパッケージがマクロを含み、バイトコンパイラーがそれを知らなければならない場合です。これはrequireによりロードされるファイルで定義される関数と変数にたいするバイトコンパイラーの警告も無効にします。

バイトコンパイルの間にトップレベルのrequireが評価されるとしても、provide呼び出しは評価されません。したがって、以下の例のようにprovideの後に同じ機能にたいするrequireを含めることにより、バイトコンパイル前に定義しているファイルを確実にロードできます。

(provide 'my-feature)  ; バイトコンパイラーには無視され、
                       ;   loadには評価される。
(require 'my-feature)  ; バイトコンパイラーにより評価される。

コンパイラーはprovideを無視して、その後に対象のファイルをロードすることによりrequireが処理されます。ファイルのロードはprovide呼び出しを実行するので、後続のrequireはファイルがロードされているときは何も行いません。

Function: provide feature &optional subfeatures

この関数は、カレントEmacsセッションにfeatureがロードされた、あるいはロードされつつあることをアナウンスします。これは、featureに関連する機能が他のLispプログラムから利用可能できる、あるいは利用可能になることを意味します。

The direct effect of calling provide is to add feature to the front of features if it is not already in that list and call any eval-after-load code waiting for it (see section ロードのためのフック). The argument feature must be a symbol. provide returns feature.

subfeaturesが与えられた場合、それはfeatureの当該バージョンによりプロバイドされる特定のサブフィーチャのセットを示すシンボルのリストであるべきです。featurepを使用して、サブフィーチャの存在をテストできます。あるパッケージの、ロードされるか、あるいはそのバージョンに存在するか不明なさまざまな部分や機能に名前を与えて使いやすくするには、そのパッケージが複雑すぎるときにサブフィーチャを使用するというのがサブフィーチャというアイデアです。例としては、ネットワーク機能の可用性のテストを参照してください。

features
     ⇒ (bar bish)

(provide 'foo)
     ⇒ foo
features
     ⇒ (foo bar bish)

オートロードによりあるファイルがロードされて、その内容の評価エラーによりストップいたとき、そのロードの間に発生した関数定義やprovide呼び出しはアンドゥされます。autoloadを参照してください。

Function: require feature &optional filename noerror

この関数はカレントEmacsセッションにおいて、featureが存在するかどうかを、((featurep feature)を使用して。以下を参照)をチェックします。引数featureはシンボルでなければなりません。

そのフィーチャが存在しない場合、requireはloadによりfilenameをロードします。filenameが与えられなかった場合は、シンボルfeatureの名前がロードするファイル名のベースとして使用されます。しかしこの場合、requireはfeatureを探すためにサフィックス‘.el’および‘.elc’の追加を強制します(圧縮ファイルのサフィックスに拡張されるかもしれません)。名前がただのfeatureというファイルは使用されません。(変数load-suffixesは要求されるLispサフィックスを正確に指定します。)

noerrorが非nilの場合は、ファイルの実際のロードにおけるエラーを抑止します。この場合、そのファイルのロードが失敗すると、requireはnilをリターンします。通常では、requireはfeatureをリターンします。

If loading the file succeeds but does not provide feature, require signals an error about the missing feature.

Function: featurep feature &optional subfeature: この関数は、カレントEmacsセッションfeatureがプロバイドされている場合(たとえばfeaturefeaturesのメンバーの場合)はtをリターンします。subfeatureが非nilの場合、この関数はサブフィーチャも同様にプロバイドされているとき(たとえばsubfeatureがシンボルfeatureのプロパティsubfeatureのメンバーのとき)だけtをリターンします。

Variable: features: この変数の値はシンボルのリストで、このシンボルはカレントEmacsセッションにロードされたフィーチャです。シンボルはそれぞれprovideを呼び出すことにより、このリストにputされたものです。リストfeatures内の要素の順番に意味はありません。

16.8 どのファイルで特定のシンボルが定義されているか

Function: symbol-file symbol &optional type

この関数は、symbolを定義しているファイルの名前をリターンします。typeがnilの場合は、どのようなタイプの定義も受け入れられます。typeがdefunの場合は関数定義、defvarは変数定義、deffaceはフェイス定義だけを指定します。

値は通常、絶対ファイル名です。定義がどのファイルにも関係しないときは、nilになることもあります。symbolがオートロード関数を指定する場合、値が拡張子なしの相対ファイル名になることもあります。

symbol-fileは変数load-history.<の値にもとづいています。

Variable: load-history

この変数の値は、ロードされたライブラリーファイルの名前を、それらが定義する関数と変数の名前、およびそれらがプロバイドまたはリクワイアするフィーチャに関連付けるalistです。

このalist内の各要素は、1つのロード済みライブラリー(スタートアップ時にプリロードされたライブラリーを含む)を記述します。要素はCARがライブラリーの絶対ファイル名(文字列)のリストです。残りのリスト要素は、以下の形式です:

var: シンボルvarが変数として定義された。
(defun . fun): 関数funが定義された。
(t . fun): 関数funは、このライブラリーがそれを関数として再定義する前はオートロードとして定義されていた。後続の要素は常に(defun . fun)で、これはfunを関数として定義する。
(autoload . fun): 関数funはオートロードとして定義された。
(defface . face): フェイスfaceが定義された。
(require . feature): フィーチャfeatureがリクワイアされた。
(provide . feature): フィーチャfeatureがプロバイドされた。
(cl-defmethod method specializers): The named method was defined by using cl-defmethod, with specializers as its specializers.
(define-type . type): The type type was defined.

load-historyの値には、CARがnilの要素が1つ含まれるかもしれません。この要素は、ファイルをvisitしていないバッファーでのeval-bufferで作成された定義を記述します。

コマンドeval-regionはload-historyを更新しますが、要素を置き換えずに、visitされているファイルの要素にたいして定義されたシンボルを追加します。evalを参照してください。

16.9 アンロード

他のLispオブジェクト用にメモリーを回収するために、ライブラリーによりロードされた関数や変数を破棄することができます。これを行うには、関数unload-featureを使用します:

Command: unload-feature feature &optional force

このコマンドはフィーチャfeatureをプロバイドしていたライブラリーをアンロードします。そのライブラリー内のdefun、defalias、defsubst、defmacro、defconst、defvar、defcustomにより定義されたすべての関数、マクロ、変数は未定義になります。その後、それらのシンボルにたいして事前に関連付けられていたオートロードをリストアします。(ロードはシンボルのautoloadプロパティにこれらを保存しています。)

以前の定義をリストアする前に、特定のフックからそのライブラリー内の関数を取り除くために、unload-featureはremove-hookを実行します。これらのフックには、名前が‘-hook’(または廃止されたサフィックス‘-hooks’)で終わる変数、加えてunload-feature-special-hooks、同様にauto-mode-alistにリストされた変数も含まれます。これは、重要なフックがすでに定義されていない関数を参照をすることにより、Emacsの機能が停止することを防ぐためです。

標準的なアンロードアクティビティは、そのライブラリー内の関数のELPプロファイリングを取り消し、そのライブラリーによりプロバイドされたフィーチャを取り消し、そのライブラリーで定義された変数に保持されたタイマーも取り消します。

これらの基準が機能不全を防ぐのに十分でない場合、ライブラリーはfeature-unload-functionという名前の明示的なアンローダーを定義できます。そのシンボルが関数として定義された場合、unload-featureは何かを行う前にまず引数なしでそれを呼び出します。これはライブラリーをアンロードしるために適切なすべてのことを行うことができます。これがnilをリターンした場合、unload-featureは通常のアンロードアクションを処理します。それ以外は、アンロード処理は完了したとみなします。

unload-featureは通常、他のライブラリーが依存するライブラリーのアンロードを拒絶します。(ライブラリーbにたいするrequireがライブラリーaに含まれる場合、aはbに依存します。)オプション引数forceが非nilの場合、依存関係は無視され、どのようなライブラリーもアンロードできます。

unload-feature関数はLispで記述されており、その動作は変数load-historyにもとづきます。

Variable: unload-feature-special-hooks: この変数には、ライブラリー内で定義された関数を取り除くために、ライブラリーをアンロードする前にスキャンされるフックのリストが保持されています。

16.10 ロードのためのフック

変数after-load-functionsを使用することにより、Emacsがライブラリーをロードするたびにコードを実行させることができます:

Variable: after-load-functions: このアブノーマルフック(abnormal hook)は、ファイルをロードした後に実行されます。フック内の各関数は1つの引数(ロードされたファイルの絶対ファイル名)で呼び出されます。

特定のライブラリーがロードされた後にコードを実行したい場合は、マクロwith-eval-after-loadを使用します:

Macro: with-eval-after-load library body…

このマクロはlibraryがロードされるたびに、ファイルlibraryのロードの最後でbodyが評価されるよう準備します。libraryがすでにロード済みの場合は、即座にbodyを評価します。

ファイル名libraryにディレクトリーや拡張子を与える必要はありません。通常は以下のようにファイル名だけを与えます:

(with-eval-after-load "edebug" (def-edebug-spec c-point t))

どのファイルが評価をトリガーできるか制限するには、ディレクトリーか拡張子、またはしの両方をlibraryに含めます。実際のファイル名(たとえばすべてのシンボリックリンク名は除外される)が、与えられた名前すべてにマッチするファイルだけが、マッチします。以下の例では、どこかのディレクトリー..../foo/barにあるmy_inst.elcやmy_inst.elc.gzは評価をトリガーしますが、my_inst.elは異なります。:

(with-eval-after-load "foo/bar/my_inst.elc" …)

libraryはフィーチャ(たとえばシンボル)でもよく、その場合(provide library)を呼び出す任意のファイルの最後にbodyが評価されます。

body内のエラーはロードをアンドゥしませんが、bodyの残りの実行を妨げます。

Normally, well-designed Lisp programs should not use with-eval-after-load. If you need to examine and set the variables defined in another library (those meant for outside use), you can do it immediately—there is no need to wait until the library is loaded. If you need to call functions defined by that library, you should load the library, preferably with require (see section 名前つき機能).

16.11 Emacs Dynamic Modules

A dynamic Emacs module is a shared library that provides additional functionality for use in Emacs Lisp programs, just like a package written in Emacs Lisp would.

Functions that load Emacs Lisp packages can also load dynamic modules. They recognize dynamic modules by looking at their file-name extension, a.k.a. “suffix”. This suffix is platform-dependent.

Variable: module-file-suffix: This variable holds the system-dependent value of the file-name extension of the module files. Its value is .so on POSIX hosts and .dll on MS-Windows.

Every dynamic module should export a C-callable function named emacs_module_init, which Emacs will call as part of the call to load or require which loads the module. It should also export a symbol named plugin_is_GPL_compatible to indicate that its code is released under the GPL or compatible license; Emacs will refuse to load modules that don’t export such a symbol.

If a module needs to call Emacs functions, it should do so through the API defined and documented in the header file emacs-module.h that is part of the Emacs distribution.

Modules can create user-ptr Lisp objects that embed pointers to C struct’s defined by the module. This is useful for keeping around complex data structures created by a module, to be passed back to the module’s functions. User-ptr objects can also have associated finalizers – functions to be run when the object is GC’ed; this is useful for freeing any resources allocated for the underlying data structure, such as memory, open file descriptors, etc.

Function: user-ptrp object: This function returns t if its argument is a user-ptr object.

Loadable modules in Emacs are enabled by using the --with-modules option at configure time.

If you write your own dynamic modules, you may wish to verify their conformance to the Emacs dynamic module API. Invoking Emacs with the --module-assertions option will help you in this matter. See Initial Options in The GNU Emacs Manual.

17 バイトコンパイル

Emacs Lispには、Lispで記述された関数を、より効率的に実行できるバイトコード(byte-code)と呼ばれる特別な表現に翻訳するコンパイラー(compiler)があります。コンパイラーはLispの関数定義をバイトコードに置き換えます。バイトコード関数が呼び出されたとき、その定義はバイトコードインタープリター(byte-code interpreter)により評価されます。

バイトコンパイルされたコードは、(本当のコンパイル済みコードのように)そのマシンのハードウェアにより直接実行されるのではなく、バイトコンパイラーにより評価されるため、バイトコードはリコンパイルしなくてもマシン間での完全な可搬性を有します。しかし、本当にコンパイルされたコードほど高速ではありません。

一般的に、任意のバージョンのEmacsはそれ以前のバージョンのEmacsにより生成されたバイトコンパイル済みコードを実行できますが、逆は成り立ちません。

あるLispファイルを常にコンパイルせずに実行したい場合は、以下のようにno-byte-compileにバインドするファイルローカル変数を配します:

;; -*-no-byte-compile: t; -*-

17.1 バイトコンパイル済みコードのパフォーマンス		バイトコンパイルによるスピードアップ例。
17.2 バイトコンパイル関数
17.3 ドキュメント文字列とコンパイル		ドキュメント文字列のダイナミックロード。
17.4 個別関数のダイナミックロード		個々の関数のダイナミックロード。
17.5 コンパイル中の評価		コンパイル時に評価されるコード。
17.6 コンパイラーのエラー		コンパイラーのエラーメッセージの扱い。
17.7 バイトコード関数オブジェクト		バイトコンパイル済み関数に使用されるデータ型。
17.8 逆アセンブルされたバイトコード		バイトコードの逆アセンブル; バイトコードの読み方。

17.1 バイトコンパイル済みコードのパフォーマンス

バイトコンパイルされた関数はCで記述されたプリミティブ関数ほど効率的ではありませんがLispで記述されたバージョンよりは高速に実行されます。以下は例です:

(defun silly-loop (n)
  "Return the time, in seconds, to run N iterations of a loop."
  (let ((t1 (float-time)))
    (while (> (setq n (1- n)) 0))
    (- (float-time) t1)))
⇒ silly-loop

(silly-loop 50000000)
⇒ 10.235304117202759

(byte-compile 'silly-loop)
⇒ [コンパイルされたコードは表示されない]

(silly-loop 50000000)
⇒ 3.705854892730713

この例では、インタープリターによる実行には10秒を要しますが、バイトコンパイルされたコードは4秒未満です。これは典型的な結果例ですが、実際の結果はさまざまでしょう。

17.2 バイトコンパイル関数

byte-compileにより、関数やマクロを個別にバイトコンパイルできます。byte-compile-fileでファイル全体、byte-recompile-directoryまたはbatch-byte-compileで複数ファイルをコンパイルできます。

Sometimes, the byte compiler produces warning and/or error messages (see section コンパイラーのエラー, for details). These messages are normally recorded in a buffer called *Compile-Log*, which uses Compilation mode. See Compilation Mode in The GNU Emacs Manual. However, if the variable byte-compile-debug is non-nil, error messages will be signaled as Lisp errors instead (see section エラー).

バイトコンパイルを意図したファイル内にマクロ呼び出しを記述する際は、注意が必要です。マクロ呼び出しはコンパイル時に展開されるので、そのマクロはEmacsにロードされる必要があります(さもないとバイトコンパイラーは正しく処理しないでしょう)。これを処理する通常の方法は、必要なマクロ定義を含むファイルをrequireフォームで指定することです。バイトコンパイラーは通常、コンパイルするコードを評価しませんが、requireフォームは指定されたライブラリーをロードすることにより特別に扱われます。誰かがコンパイルされたプログラムを実行する際に、マクロ定義ファイルのロードを回避するには、require呼び出しの周囲にeval-when-compileを記述します(コンパイル中の評価を参照)。詳細はマクロとバイトコンパイルを参照してください。

インライン(defsubst)の関数は、これほど面倒ではありません。定義が判明する前にそのような関数呼び出しをコンパイルした場合でも、その呼び出しは低速になるだけで、正しく機能するでしょう。

Function: byte-compile symbol

この関数はsymbolの関数定義をバイトコンパイルして、以前の定義をコンパイルされた定義に置き換えます。symbolの関数定義は、その関数にたいする実際のコードでなければなりません。byte-compileはインダイレクト関数を処理しません。リターン値は、symbolのコンパイルされた定義であるバイトコード関数ブジェクトです(バイトコード関数オブジェクトを参照)。

(defun factorial (integer)
  "INTEGERの階乗を計算する。"
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
⇒ factorial

(byte-compile 'factorial)
⇒
#[(integer)
  "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207"
  [integer 1 * factorial]
  4 "Compute factorial of INTEGER."]

If symbol’s definition is a byte-code function object, byte-compile does nothing and returns nil. It does not compile the symbol’s definition again, since the original (non-compiled) code has already been replaced in the symbol’s function cell by the byte-compiled code.

byte-compileの引数としてlambda式も指定できます。この場合、関数は対応するコンパイル済みコードをリターンしますが、それはどこにも格納されません。

Command: compile-defun &optional arg

このコマンドはポイントを含むdefunを読み取りそれをコンパイルして、結果を評価します。実際に関数定義であるようなdefunでこれを使用した場合は、その関数のコンパイル済みバージョンをインストールする効果があります。

compile-defun normally displays the result of evaluation in the echo area, but if arg is non-nil, it inserts the result in the current buffer after the form it has compiled.

Command: byte-compile-file filename &optional load

この関数はfilenameという名前のLispコードファイルを、バイトコードのファイルにコンパイルします。出力となるファイルの名前は、サフィックス‘.el’を‘.elc’に変更することにより作成されます。filenameが‘.el’で終了しない場合は、‘.elc’をfilenameの最後に付け足します。

コンパイルは入力ファイルから1つのフォームを逐次読み取ることにより機能します。フォームが関数またはマクロの場合は、コンパイル済みの関数またはマクロが書き込まれます。それ以外のフォームはまとめられて、まとめられたものごとにコンパイルされ、そのファイルが読まれたとき実行されるようにコンパイルされたコードが書き込まれます。入力ファイルを読み取る際、すべてのコメントは無視されます。

このコマンドはエラーのないときはt、それ以外はnilをリターンします。インタラクティブに呼び出されたときは、ファイル名の入力をもとめます。

loadが非nilの場合、このコマンドはコンパイルした後にコンパイルされたファイルをロードします。インタラクティブに呼び出された場合、loadはプレフィクス引数です。

$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el

(byte-compile-file "~/emacs/push.el")
     ⇒ t

$ ls -l push*
-rw-r--r-- 1 lewis lewis 791 Oct  5 20:31 push.el
-rw-rw-rw- 1 lewis lewis 638 Oct  8 20:25 push.elc

Command: byte-recompile-directory directory &optional flag force

このコマンドは、directory(またはそのサブディレクトリー)内の、リコンパイルを要するすべての‘.el’ファイルをリコンパイルします。‘.elc’ファイルが存在し、それが‘.el’より古いファイルは、リコンパイルが必要です。

‘.el’ファイルに対応する‘.elc’ファイルが存在しない場合、何を行うかをflagで指定します。nilの場合、このコマンドはこれらのファイルを無視します。flagが0のときは、それらをコンパイルします。nilと0以外の場合は、それらのファイルをコンパイルするかユーザーに尋ね、同様にそれぞれのサブディレクトリーについても尋ねます。

インタラクティブに呼び出された場合、byte-recompile-directoryはdirectoryの入力を求め、flagはプレフィクス引数になります。

forceが非nilの場合、このコマンドは‘.elc’ファイルのあるすべての‘.el’ファイルをリコンパイルします。

リターン値は不定です。

Function: batch-byte-compile &optional noforce

この関数は、コマンドラインで指定されたファイルにたいして、byte-compile-fileを実行します。この関数は処理が完了するとEmacsをkillするので、Emacsのバッチ実行だけで使用しなければなりません。1つのファイルでエラーが発生しても、それにより後続のファイルにたいする処理が妨げられることはありませんが、そのファイルにたいする出力ファイルは生成されず、Emacsプロセスは0以外のステータスコードで終了します。

noforceが非nilの場合、この関数は最新の‘.elc’ファイルがあるファイルをリコンパイルしません。

$ emacs -batch -f batch-byte-compile *.el

17.3 ドキュメント文字列とコンパイル

When Emacs loads functions and variables from a byte-compiled file, it normally does not load their documentation strings into memory. Each documentation string is dynamically loaded from the byte-compiled file only when needed. This saves memory, and speeds up loading by skipping the processing of the documentation strings.

この機能には欠点があります。コンパイル済みのファイルを削除、移動、または(新しいバージョンのコンパイル等で)変更した場合、Emacsは前にロードされた関数や変数のドキュメント文字列にアクセスできなくなるでしょう。このような問題は通常、あなた自身がEmacsをビルドした場合に、そのLispファイルを編集、および/またはリコンパイルしたときだけ発生します。この問題は、リコンパイル後にそれぞれのファイルをリロードするだけで解決します。

バイトコンパイルされたファイルからのドキュメント文字列のダイナミックロードは、バイトコンパイルされたファイルごとに、コンパイル時に決定されます。これはオプションbyte-compile-dynamic-docstringsにより、無効にできます。

User Option: byte-compile-dynamic-docstrings

これが非nilの場合、バイトコンパイラーはドキュメント文字列をダイナミックロードするようセットアップしたコンパイル済みファイルを生成します。

特定のファイルでダイナミックロード機能を無効にするには、以下のようにヘッダー行(Local Variables in Files in The GNU Emacs Manualを参照)で、このオプションにnilをセットします。

-*-byte-compile-dynamic-docstrings: nil;-*-

これは主に、あるファイルを変更しようとしていて、そのファイルをすでにロード済みのEmacsセッションがファイルを変更した際にも正しく機能し続けることを望む場合に有用です。

Internally, the dynamic loading of documentation strings is accomplished by writing compiled files with a special Lisp reader construct, ‘#@count’. This construct skips the next count characters. It also uses the ‘#$’ construct, which stands for the name of this file, as a string. Do not use these constructs in Lisp source files; they are not designed to be clear to humans reading the file.

17.4 個別関数のダイナミックロード

ファイルをコンパイルするとき、オプションでダイナミック関数ロード(dynamic function loading)機能(laxyロード(lazy loading)とも呼ばれる)を有効にできます。ダイナミック関数ロードでは、ファイルのロードでファイル内の関数定義は完全には読み込まれません。かわりに、各関数定義にはそのファイルを参照するプレースホルダーが含まれます。それぞれ関数が最初に呼び出されるときに、そのプレースホルダーを置き換えるために、ファイルから完全な定義が読み込まれます。

ダイナミック関数ロードの利点は、ファイルのロードがより高速になることです。ユーザーが呼び出せる関数を多く含むファイルにとって、それらの関数のうち1つを使用したら、おそらく残りの関数も使用するというのでなければ、これは利点です。多くのキーボードコマンドを提供する特化したモードは、このパターンの使い方をする場合があります。ユーザーはそのモードを呼び出すかもしれませんが、使用するのはそのモードが提供するコマンドのわずか一部です。

ダイナミックロード機能には、いくつか不利な点があります:

ロード後にコンパイル済みファイルを削除や移動した場合、Emacsはまだロードされていない残りの関数定義をロードできなくなる。
(新しいバージョンのコンパイル等で)コンパイル済みファイルを変更した場合、まだロードされていない関数のロードを試みると、通常は無意味な結果となる。

このような問題は、通常の状況でインストールされたEmacsファイルでは決して発生しません。しかし、あなたが変更したLispファイルでは発生し得ます。それぞれのファイルをリコンパイルしたらすぐに、新たなコンパイル済みファイルをリロードするのが、これらの問題を回避する一番簡単な方法です。

コンパイル時に変数byte-compile-dynamicが非nilの場合、バイトコンパイラーはダイナミック関数ロード機能を使用します。ダイナミックロードが望ましいのは特定のファイルにたいしてだけなので、この変数をグローバルにセットしないでください。そのかわりに、特定のソースファイルのファイルローカル変数で、この機能を有効にしてください。たとえば、ソースファイルの最初の行に以下のテキストを記述することにより、これを行うことができます:

-*-byte-compile-dynamic: t;-*-

Variable: byte-compile-dynamic: これが非nilの場合、バイトコンパイラーはダイナミック関数ロードのためにセットアップされたコンパイル済みファイルを生成します。

Function: fetch-bytecode function: functionがバイトコード関数オブジェクトの場合、それがまだ完全にロードされていなければ、バイトコンパイル済みのファイルからのfunctionのバイトコードのロードを完了させます。それ以外は、何も行いません。この関数は、常にfunctionをリターンします。

17.5 コンパイル中の評価

これらの機能により、プログラムのコンパイル中に評価されるコードを記述できます。

Special Form: eval-and-compile body…

このフォームは、それを含むコードがコンパイルされるとき、および(コンパイルされているかいないかに関わらず)実行されるときの両方で、bodyが評価されるようにマークします。

bodyを別のファイルに配し、そのファイルをrequireで参照すれば、同様の結果が得られます。これはbodyが大きいとき望ましい方法です。事実上、requireは自動的にeval-and-compileされ、そのパッケージはコンパイル時と実行時の両方でロードされます。

autoloadも実際はeval-and-compileされます。これはコンパイル時に認識されるので、そのような関数の使用により警告“not known to be defined”は生成されません。

ほとんどのeval-and-compileの使用は、完全に妥当であると言えます。

あるマクロがマクロの結果を構築するためのヘルパー関数をもち、そのマクロがそのパッケージにたいしてローカルと外部の両方で使用される場合には、コンパイル時と後の実行時にそのヘルパー関数を取得するために、eval-and-compileを使用すべきです。

関数がプログラム的に(fsetで)定義されている場合には、それがコンパイル時、同様に実行時に行われるように使用でき、それらの関数への呼び出しはチェックされます(“not known to be defined”の警告は抑えられます)。

Special Form: eval-when-compile body…

このフォームは、bodyがコンパイル時に評価され、コンパイルされたプログラムがロードされるときは評価されないようにマークします。コンパイラーによる評価の結果は、コンパイル済みのプログラム内の定数となります。ソースファイルをコンパイルではなくロードした場合、bodyは通常どおり評価されます。

生成するために何らかの計算が必要な定数がある場合、eval-when-compileはコンパイル時にそれを行なうことができます。たとえば、

(defvar my-regexp
  (eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))

他のパッケージを使用しているが、そのパッケージのマクロ(バイトコンパイラーはそれらを展開します)だけが必要な場合、それらを実行せずにコンパイル用にロードさせるためにeval-when-compileを使用できます。たとえば、

(eval-when-compile
  (require 'my-macro-package))

これらの事項は、マクロおよびdefsubst関数がローカルに定義され、そのファイル内だけで使用されることを要求します。これらは、そのファイルのコンパイルに必要ですが、コンパイル済みファイルの実行には、ほとんどの場合必要ありません。たとえば、

(eval-when-compile
  (unless (fboundp 'some-new-thing)
    (defmacro 'some-new-thing ()
      (compatibility code))))

これは大抵他のバージョンのEmacsとの互換性にたいする保証だけのためのコードにたいして有用です。

Common Lispに関する注意: トップレベルでは、eval-when-compileはCommon Lispのイディオム(eval-when (compile eval) …)に類似しています。トップレベル以外では、Common Lispのリーダーマクロ‘#.’(ただし解釈時を除く)が、eval-when-compileと近いことを行います。

17.6 コンパイラーのエラー

バイトコンパイルのエラーメッセージと警告メッセージは、*Compile-Log*という名前のバッファーにプリントされます。これらのメッセージには、問題となる箇所を示すファイル名と行番号が含まれます。これらのメッセージにたいして、コンパイラー出力を操作する通常のEmacsコマンドが使用できます。

When an error is due to invalid syntax in the program, the byte compiler might get confused about the error’s exact location. One way to investigate is to switch to the buffer *Compiler Input*. (This buffer name starts with a space, so it does not show up in the Buffer Menu.) This buffer contains the program being compiled, and point shows how far the byte compiler was able to read; the cause of the error might be nearby. See section 無効なLisp構文のデバッグ, for some tips for locating syntax errors.

定義されていない関数や変数の使用は、バイトコンパイラーにより報告される警告のタイプとしては一般的です。そのような警告では、定義されていない関数や変数を使用した位置ではなく、そのファイルの最後の行の行番号が報告されるので、それを見つけるには手作業で検索しなければなりません。

定義のない関数や変数の警告が間違いだと確信できる場合には、警告を抑制する方法がいくつかあります:

関数funcへの特定の呼び出しにたいする警告は、それを条件式でfboundpによるテストを行なうことで抑制できます:
```
(if (fboundp 'func) ...(func ...)...)
```
funcへの呼び出しはif文のthen-form内になければならず、funcはfboundp呼び出し内でクォートされていなければなりません。(この機能はcondでも同様に機能します。)
同じように、変数variableの特定の使用についの警告を、条件式内のboundpテストで抑制できます:
```
(if (boundp 'variable) ...variable...)
```
variableへの参照はif文のthen-form内になければならず、variableはboundp呼び出し内でクォートされていなければなりません。
You can tell the compiler that a function is defined using declare-function. See section コンパイラーへの定義済み関数の指示.
Likewise, you can tell the compiler that a variable is defined using defvar with no initial value. (Note that this marks the variable as special, i.e. dynamically bound, but only within the current lexical scope, or file if at top-level.) See section グローバル変数の定義.

with-no-warnings構成を使用して特定の式にたいするコンパイラーのすべての任意の警告を抑制することもできます:

Special Form: with-no-warnings body…

実行時には〜これは(progn body...)と等価ですが、コンパイラーはbodyの中で起こるいかなる事項にたいしても警告を発しません。

わたしたちは、あなたが抑制したいと意図する警告以外の警告を失わないようにするために、可能な限り小さいコード断片にたいしてこの構成を使用することを推奨します。

変数byte-compile-warningsをセットすることにより、コンパイラーの警告をより詳細に制御できます。詳細は、変数のドキュメント文字列を参照してください。

Sometimes you may wish the byte-compiler warnings to be reported using error. If so, set byte-compile-error-on-warn to a non-nil value.

17.7 バイトコード関数オブジェクト

バイトコンパイルされた関数は、特別なデータ型、バイトコード関数オブジェクト(byte-code function objects)をもちます。関数呼び出しとしてそのようなオブジェクトが出現したとき、Emacsはそのバイトコードを実行するために、常にバイトコードインタープリターを使用します。

内部的には、バイトコード関数オブジェクトはベクターによく似ています。バイトコード関数オブジェクトの要素には、arefを通じてアクセスできます。バイトコード関数オブジェクトのプリント表現(printed representation)はベクターに似ていて、開き‘[’の前に‘#’が追加されます。バイト関数オブジェクトは少なくとも4つの要素をもたねばならず、要素数に上限はありません。しかし通常使用されるのは、最初の6要素です。これらは:

argdesc

The descriptor of the arguments. This can either be a list of arguments, as described in 引数リストのその他機能, or an integer encoding the required number of arguments. In the latter case, the value of the descriptor specifies the minimum number of arguments in the bits zero to 6, and the maximum number of arguments in bits 8 to 14. If the argument list uses &rest, then bit 7 is set; otherwise it’s cleared.

If argdesc is a list, the arguments will be dynamically bound before executing the byte code. If argdesc is an integer, the arguments will be instead pushed onto the stack of the byte-code interpreter, before executing the code.

byte-code

バイトコード命令を含む文字列。

constants

バイトコードにより参照されるLispオブジェクトのベクター。関数名と変数名に使用されるシンボルが含まれる。

stacksize

この関数が要するスタックの最大サイズ。

docstring

(もしあれば)ドキュメント文字列。それ以外はnil。ドキュメント文字列がファイルに格納されている場合、値は数字かリストかもしれない。本当のドキュメント文字列の取得には、関数documentationを使用する(ドキュメント文字列へのアクセスを参照)。

interactive

(もしあれば)インタラクティブ仕様。文字列かLisp式。インタラクティブでない関数ではnil。

以下は、バイトコード関数オブジェクトのプリント表現の例です。これはコマンドbackward-sexpの定義です。

#[256
  "\211\204^G^@\300\262^A\301^A[!\207"
  [1 forward-sexp]
  3
  1793299
  "^p"]

バイトコードオブジェクトを作成する原始的な方法は、make-byte-codeです:

Function: make-byte-code &rest elements: この関数はelementsを要素とするバイトコードオブジェクトを構築して、リターンします。

あなた自身が要素を収集してバイトコード関数を構築しないでください。それらが矛盾する場合、その関数の呼び出しによりEmacsがクラッシュするかもしれません。これらのオブジェクトの作成は、常にバイトコンパイラーにまかせてください。バイトコンパイラーは、要素を矛盾なく構築します(願わくば)。

17.8 逆アセンブルされたバイトコード

人はバイトコードを記述しません。それはバイトコンパイラーの仕事です。しかし、好奇心を満たすために、わたしたちはディスアセンブラを提供しています。ディスアセンブラは、バイトコードを人間が読めるフォームに変換します。

バイトコードインタープリターは、シンプルなスタックマシンとして実装されています。これは値を自身のスタックにpushして、計算で使用するためにそれらをpopして取り出し、おの結果を再びそのスタックにpushして戻します。バイトコード関数がリターンするときは、スタックから値をpopして取り出し、その関数の値としてリターンします。

それに加えてスタックとバイトコード関数は、値を変数とスタックの間で転送することにより、普通のLisp変数を使用したり、バインドおよびセットすることができます。

Command: disassemble object &optional buffer-or-name

このコマンドは、objectにたいするディスアセンブルされたコードを表示します。インタラクティブに使用した場合、またはbuffer-or-nameがnilか省略された場合は、*Disassemble*という名前のバッファーに出力します。buffer-or-nameが非nilの場合は、バッファーもしくは既存のバッファーの名前でなければなりません。その場合は、そのバッファーのポイント位置に出力され、ポイントは出力の前に残りされます。

引数objectには関数名、ラムダ式(ラムダ式を参照)、またはバイトコードオブジェクト(バイトコード関数オブジェクトを参照)を指定できます。ラムダ式の場合、disassembleはそれをコンパイルしてから、そのコンパイル済みコードをディスアセンブルします。

以下にdisassemble関数を使用した例を2つ示します。バイトコードとLispソースを関連付ける助けとなるように、説明的なコメントを追加してあります。これらのコメントは、disassembleの出力にはありません。

(defun factorial (integer)
  "Compute factorial of an integer."
  (if (= 1 integer) 1
    (* integer (factorial (1- integer)))))
     ⇒ factorial

(factorial 4)
     ⇒ 24

(disassemble 'factorial)
     -| byte-code for factorial:
 doc: Compute factorial of an integer.
 args: (integer)

0   varref   integer      ; integerの値を取得して
                          ;   それをスタック上にpushする。
1   constant 1            ; スタック上に1をpushする。

2   eqlsign               ; 2つの値をスタックからpopして取り出し、
                          ;   それらを比較して結果をスタック上にpushする。

3   goto-if-nil 1         ; スタックのトップをpopしてテストする。
                          ;   nilなら1へ、それ以外はcontinue。
6   constant 1            ; スタックのトップに1をpushする。
7   return                ; スタックのトップの要素をリターンする。

8:1 varref   integer      ; integerの値をスタック上にpushする。
9   constant factorial    ; factorialをスタック上にpushする。
10  varref   integer      ; integerの値をスタック上にpushする。
11  sub1                  ; integerをpopして値をデクリメントする。
                          ;   スタック上に新しい値をpushする。
12  call     1            ; スタックの最初(トップ)の要素を引数として
                          ;   関数factorialを呼び出す。
                          ;   リターン値をスタック上にpushする。

13 mult                   ; スタックのトップ2要素をpopして取り出し乗じ
                          ;   結果をスタック上にpushする。
14 return                 ; スタックのトップ要素をリターンする。

silly-loopは幾分複雑です:

(defun silly-loop (n)
  "Return time before and after N iterations of a loop."
  (let ((t1 (current-time-string)))
    (while (> (setq n (1- n))
              0))
    (list t1 (current-time-string))))
     ⇒ silly-loop

(disassemble 'silly-loop)
     -| byte-code for silly-loop:
 doc: Return time before and after N iterations of a loop.
 args: (n)

0   constant current-time-string  ; current-time-stringを
                                  ;   スタック上のトップにpushする。

1   call     0            ; 引数なしでcurrent-time-stringを呼び出し
                          ;   結果をスタック上にpushする。

2   varbind  t1           ; スタックをpopしてt1にpopされた値をバインドする。

3:1 varref   n            ; 環境からnの値を取得して
                          ;   その値をスタック上にpushする。
4   sub1                  ; スタックのトップから1を減ずる。

5   dup                   ; スタックのトップを複製する。
                          ;   たとえばスタックのトップをコピーしてスタック上にpushする。
6   varset   n            ; スタックのトップをpopして
                          ;   nをその値にバインドする。

;; (要はシーケンスdup varsetはpopせずに
;;  スタックのトップをnの値にコピーする。)

7   constant 0            ; スタック上に0をpushする。
8   gtr                   ; スタックのトップ2値をpopして取り出し
                          ;   nが0より大かテストし
                          ;   結果をスタック上にpushする。

9   goto-if-not-nil 1     ; n > 0なら1へ
                          ;   (これはwhile-loopを継続する)
                          ;   それ以外はcontinue。

12  varref   t1           ; t1の値をスタック上にpushする。
13  constant current-time-string  ; current-time-stringを
                                  ;   スタックのトップにpushする。
14  call     0            ; 再度current-time-stringを呼び出す。

15  unbind   1            ; ローカル環境のt1をアンバインドする。
16  list2                 ; スタックのトップ2要素をpopして取り出し
                          ;   それらのリストを作りスタック上にpushする。
17  return                ; スタックのトップの値をリターンする。

18 Lispプログラムのデバッグ

Emacs Lispプログラム内の問題を見つけて詳細に調べる方法が、いくつかあります。

プログラム実行中に問題が発生した場合は、Lisp評価機能をサスペンドするためにビルトインのEmacs Lispデバッガを使用して、評価機能の内部状態の調査および/または変更を行なうことができます。
Emacs Lispにたいするソースレベルデバッガの、Edebugを使用できます。
You can trace the execution of functions involved in the problem using the tracing facilities provided by the trace.el package. This package provides the functions trace-function-foreground and trace-function-background for tracing function calls, and trace-values for adding values of select variables to the trace. For the details, see the documentation of these facilities in trace.el.
文法的な問題によりLispがプログラムを読むことさえできない場合は、Lisp編集コマンドを使用して該当箇所を見つけることができます。
バイトコンパイラーがプログラムをコンパイルするとき、コンパイラーにより生成されるエラーメッセージと警告メッセージを調べることができます。コンパイラーのエラーを参照してください。
Testcoverパッケージを使用してプログラムのテストカバレッジを行なえます。
ERTパッケージを使用して、プログラムにたいするリグレッションテストを記述できます。the ERT manual in ERT: Emacs Lisp Regression Testingを参照してください。
プログラムをプロファイルして、プログラムをより効果的にするためのヒントを取得できます。

入出力の問題をデバックする便利なその他のツールに、ドリブルファイル(dribble file: 端末の入力を参照)と、open-termscript関数(端末の出力)があります。

18.1 Lispデバッガ

普通のLispデバッガは、フォーム評価のサスペンド機能を提供します。評価がサスペンド(一般的にはbreakの状態として知られる)されている間、実行時スタックを調べたり、ローカル変数やグローバル変数の値を調べたり変更することができます。breakは再帰編集(recursive edit)なので、Emacsの通常の編集機能が利用可能です。デバッガにエンターするようにプログラムを実行することさえ可能です。再帰編集を参照してください。

18.1.1 エラーによるデバッガへのエンター		エラー発生時にデバッガにエンターする。
18.1.2 無限ループのデバッグ		exitしないプログラムの停止デバッグ。
18.1.3 関数呼び出しによるデバッガへのエンター		特定の関数が呼び出されたときにデバッガにエンターする。
18.1.4 Entering the debugger when a variable is modified		Entering it when a variable is modified.
18.1.5 明示的なデバッガへのエントリー		プログラム内の特定箇所でデバッガにエンターする。
18.1.6 デバッガの使用		デバッガが行なうこと: そこで何を目にするか。
18.1.7 デバッガのコマンド		デバッガで使用するコマンド。
18.1.8 デバッガの呼び出し		関数`debug`の呼び出し方。
18.1.9 デバッガの内部		デバッガのサブルーチン、およびグローバル変数。

18.1.1 エラーによるデバッガへのエンター

デバッガに入る一番重要なタイミングは、Lispエラーが発生したときです。デバッガでは、エラーの直接原因を調査できます。

しかしデバッガへのエンターは、エラーによる通常の結末ではありません。多くのコマンドは不適切に呼び出されたときにLispエラーをシグナルするので、通常の編集の間にこれが発生するたびデバッガにエンターするのは、とても不便でしょう。したがって、エラーの際にデバッガにエンターしたい場合は、変数debug-on-errorに非nilをセットします。(コマンドtoggle-debug-on-errorは、これを簡単に行う方法を提供します。)

User Option: debug-on-error

この変数はエラーがシグナルされ、それがハンドルされていないときに、デバッガが呼び出されるかどうかを決定します。debug-on-errorがtの場合は、debug-ignored-errors(以下を参照)にリストされているエラーを除く、すべての種類のエラーがデバッガを呼び出します。nilの場合は、デバッガを呼び出しません。

値にはエラー条件(エラーをシグナルする方法を参照)のリストも指定できます。その場合、このリスト内のエラー条件だけにより、デバッガが呼び出されます(debug-ignored-errorsにもリストされているエラー条件は除外されます)。たとえば、debug-on-errorをリスト(void-variable)にセットした場合には、値をもたない変数に関するエラーにたいしてだけデバッガが呼び出されます。

eval-expression-debug-on-errorがこの変数をオーバーライドする場合がいくつかあることに注意してください(以下を参照)。

この変数が非nilのとき、Emacsはプロセスフィルター関数と番兵(sentinel)の周囲にエラーハンドラーを作成しません。したがって、これらの関数内でのエラーは、デバッガを呼び出します。プロセスを参照してください。

User Option: debug-ignored-errors

この変数は、debug-on-errorの値に関わらず、デバッガにエンターすべきでないエラーを指定します。変数の値はエラー条件のシンボル、および/または正規表現のリストです。エラーがこれら条件シンボルのいずれか、またはエラーメッセージが正規表現のいずれかにマッチする場合、そのエラーはデバッガにエンターしません。

この変数の通常の値にはuser-errorと、同様に編集中にしばしば発生するがLispプログラムのバグによるものはほとんどない、いくつかのエラーが含まれます。しかし、“ほとんどない”は“絶対ない”ではありません。あなたのプログラムがこのリストにマッチするエラーにより機能しない場合は、そのエラーをデバッグするために、このリストの変更を試みるのもよいでしょう。通常はdebug-ignored-errorsをnilにセットしておくのが、もっとも簡単な方法です。

User Option: eval-expression-debug-on-error

If this variable has a non-nil value (the default), running the command eval-expression causes debug-on-error to be temporarily bound to t. See Evaluating Emacs-Lisp Expressions in The GNU Emacs Manual.

eval-expression-debug-on-errorがnilの場合は、eval-expressionの間もdebug-on-errorの値は変更されません。

User Option: debug-on-signal

condition-caseによりキャッチされたエラーは通常、決してデバッガを呼び出しません。condition-caseは、デバッガがそのエラーをハンドルする前に、エラーをハンドルする機会を得ます。

debug-on-signalを非nil値に変更した場合は、condition-caseの存在如何に関わらず、すべてのエラーにおいてデバッガが最初に機会を得ます。(デバッガを呼び出すためには、依然としてそのエラーがdebug-on-errorとdebug-ignored-errorsで指定された条件を満たさなければなりません。)

For example, setting this variable is useful to get a backtrace from code evaluated by emacsclient’s --eval option. If Lisp code evaluated by emacsclient signals an error while this variable is non-nil, the backtrace will popup in the running Emacs.

警告: この変数を非nilにセットすると、芳しくない効果があるかもしれません。Emacsのさまざまな部分で処理の通常の過程としてエラーがキャッチされており、そのエラーが発生したことに気づかないことさえあるかもしれません。condition-caseでラップされたコードをデバッグする必要がある場合は、condition-case-unless-debug(see section エラーを処理するコードの記述を参照)の使用を考慮してください。

User Option: debug-on-event: debug-on-eventをスペシャルイベント(スペシャルイベントを参照)にセットした場合は、Emacsはspecial-event-mapをバイパスして、このイベントを受け取ると即座にデバッガへのエンターを試みます。現在のところサポートされる値は、シグナルSIGUSR1およびSIGUSR2に対応する値だけです(これがデフォルトです)。これはinhibit-quitがセットされていて、それ以外はEmacsが応答しない場合に有用かもしれません。

Variable: debug-on-message: debug-on-messageに正規表現をセットした場合には、それにマッチするメッセージがエコーエリアに表示されると、Emacsはデバッガにエンターします。たとえば、これは特定のメッセージの原因を探すのに有用かもしれません。

initファイルロード中に発生したエラーをデバッグするには、オプション‘--debug-init’を使用します。これはinitファイルロードの間にdebug-on-errorをtにバインドして、通常はinitファイル内のエラーをキャッチするcondition-caseをバイパスします。

18.1.2 無限ループのデバッグ

プログラムが無限にループしてリターンできないとき、最初の問題はそのループをいかに停止するかです。ほとんどのオペレーティングシステムでは、(quitさせる)C-gでこれを行うことができます。quitを参照してください。

普通のquitでは、なぜそのプログラムがループしたかについての情報は与えられません。変数debug-on-quitに非nilをセットすることにより、より多くの情報を得ることができます。無限ループの途中でデバッガを実行すれば、デバッガからステップコマンドで先へ進むことができます。ループ全体をステップで追えば、問題を解決するために十分な情報が得られるでしょう。

C-gによるquitはエラーとは判断されないので、C-gのハンドルにdebug-on-errorは効果がありません。同じように、debug-on-quitはエラーにたいして効果がありません。

User Option: debug-on-quit: この変数は、quitがシグナルされ、それがハンドルされていないときに、デバッガを呼び出すかどうかを決定します。debug-on-quitが非nilの場合は、quit(つまりC-gをタイプ)したときは常にデバッガが呼び出されます。debug-on-quitがnil(デフォルト)の場合は、quitしてもデバッガは呼び出されません。

18.1.3 関数呼び出しによるデバッガへのエンター

プログラムの途中で発生する問題を調べるための有用なテクニックの1つは、特定の関数が呼び出されたときデバッガにエンターする方法です。問題が発生した関数にこれを行い、その関数をステップで追ったり、問題箇所の少し手前の関数呼び出しでこれを行い、その関数をステップオーバーしてその後をステップで追うことができます。

Command: debug-on-entry function-name

この関数は、function-nameが呼び出されるたびにデバッガの呼び出しを要求します。

Lispコードで定義された任意の関数およびマクロは、インタープリターに解釈されたコードかコンパイル済みのコードかに関わらず、エントリーにbreakをセットできます。その関数がコマンドの場合は、Lispから呼び出されたときと、インタラクティブに呼び出されたとき、デバッガにエンターします。(たとえばCで記述された)プリミティブ関数にも、この方法でdebug-on-entryをセットできますが、そのプリミティブがLispコードから呼び出されたときだけ効果があります。debug-on-entryはスペシャルフォームにはセットできません。

debug-on-entryがインタラクティブに呼び出されたときは、ミニバッファーでfunction-nameの入力を求めます。その関数がすでにエントリーでデバッガを呼び出すようにセットアップされていた場合、debug-on-entryは何も行いません。debug-on-entryは常にfunction-nameをリターンします。

以下は、この関数の使い方を説明するための例です:

(defun fact (n)
  (if (zerop n) 1
      (* n (fact (1- n)))))
     ⇒ fact

(debug-on-entry 'fact)
     ⇒ fact

(fact 3)

------ Buffer: *Backtrace* ------
Debugger entered--entering a function:
* fact(3)
  eval((fact 3))
  eval-last-sexp-1(nil)
  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
------ Buffer: *Backtrace* ------

Command: cancel-debug-on-entry &optional function-name: この関数はfunction-nameにたいするdebug-on-entryの効果をアンドゥします。インタラクティブに呼び出されたときは、ミニバッファーでfunction-nameの入力を求めます。function-nameが省略された、あるいはnilの場合は、すべての関数にたいするbreak-on-entryをキャンセルします。エントリー時にbreakするようセットアップされていない関数にcancel-debug-on-entryを呼び出したときは、何も行いません。

18.1.4 Entering the debugger when a variable is modified

Sometimes a problem with a function is due to a wrong setting of a variable. Setting up the debugger to trigger whenever the variable is changed is a quick way to find the origin of the setting.

Command: debug-on-variable-change variable

This function arranges for the debugger to be called whenever variable is modified.

It is implemented using the watchpoint mechanism, so it inherits the same characteristics and limitations: all aliases of variable will be watched together, only dynamic variables can be watched, and changes to the objects referenced by variables are not detected. For details, see Running a function when a variable is changed..

Command: cancel-debug-on-variable-change &optional variable: This function undoes the effect of debug-on-variable-change on variable. When called interactively, it prompts for variable in the minibuffer. If variable is omitted or nil, it cancels break-on-change for all variables. Calling cancel-debug-on-variable-change does nothing to a variable which is not currently set up to break on change.

18.1.5 明示的なデバッガへのエントリー

プログラム内の特定箇所に式(debug)を記述することにより、その箇所でデバッガが呼び出されるようにできます。これを行うにはソースファイルをvisitして、適切な箇所にテキスト‘(debug)’を挿入し、C-M-x(Lispモードでのeval-defunにたいするキーバインド)をタイプします。警告: 一時的なデバッグ目的のためにこれを行なう場合は、ファイルを保存する前に確実にアンドゥしてください!

‘(debug)’を挿入する箇所は、追加フォームが評価されることができ、その値を無視することができる箇所でなければなりません。(‘(debug)’の値が無視されない場合が、プログラムの実行が変更されてしまうでしょう!) 一般的にもっとも適した箇所は、prognまたは暗黙的なprogn(順序を参照)の内部です。

デバッグ命令を配したいソースコード中の正確な箇所がわからないが、特定のメッセージが表示されたときにバックトレースを表示したい場合は、意図するメッセージにマッチする正規表現をdebug-on-messageにセットできます。

18.1.6 デバッガの使用

デバッガにエンターすると、その前に選択されていたウィンドウを1つのウィンドウに表示し、他のウィンドウに*Backtrace*という名前のバッファーを表示します。backtraceバッファーには、現在実行されているLisp関数の各レベルが1行ずつ含まれます。このバッファーの先頭は、デバッガが呼び出された理由を説明するメッセージ(デバッガがエラーにより呼び出された場合はエラーメッセージや関連するデータなど)です。

backtraceバッファーは読み取り専用で、文字キーにデバッガコマンドが定義されたDebuggerモードという特別なメジャーモードを使用します。通常のEmacs編集コマンドが利用できます。したがって、エラー時に編集されていたバッファーを調べるためにウィンドウを切り替えたり、バッファーを切り替えやファイルのvisit、その他一連の編集処理を行なうことができます。しかしデバッガは再帰編集レベル(再帰編集を参照)にあり、編集が終わったらそれはbacktraceバッファーに戻って、(qコマンドで)デバッガをexitできます。デバッガをexitすることにより、再帰編集を抜け出し、backtraceバッファーはバリー(bury: 覆い隠す)されます。(変数debugger-bury-or-killwをセットすることにより、backtraceバッファーでqコマンドが何を行うかをカスタマイズできます。たとえば、バッファーをバリーせずにkillしたい場合は、この変数をkillにセットします。他の値については、変数のドキュメントを調べてください。)

デバッガにエンターしたとき、eval-expression-debug-on-errorに一致するように変数debug-on-errorが一時的にセットされます。変数eval-expression-debug-on-errorが非nilの場合、debug-on-errorは一時的にtにセットされます。これは、デバッグセッション行っている間にさらにエラーが発生すると、(デフォルトでは)他のbacktraceがトリガーされることを意味します。これが望ましくない場合は、debugger-mode-hook内でeval-expression-debug-on-errorをnilにセットするか、debug-on-errorをnilにセットすることができます。

backtraceバッファーは、実行されている関数と、その関数の引数の値を示します。しのフレームを示す行にポイントを移動して、スタックフレームを指定することもできます。(スタックフレームとは、Lispインタープリターがある関数への特定の呼び出しを記録する場所のことです。) 行ポイントがオンのフレームが、カレントフレーム(current frame)となります。デバッガコマンドのいくつかは、カレントフレームを処理します。ある行がスター(star)で始まる場合は、そのフレームをexitすることにより再びデバッガが呼び出されることを意味します。これは関数のリターン値を調べるとき有用です。

関数名にアンダーラインが引かれている場合は、デバッガがその関数のソースコードも位置を知っていることを意味します。その名前をマウスでクリックするか、そこに移動してRETをタイプして、ソースコードをvisitできます。

デバッガはデバッガ自身のスタックフレーム数を想定するため、バイトコンパイルされて実行されなければなりません。デバッガがインタープリターに解釈されて実行されているとき、これらの想定は正しくなくなります。

18.1.7 デバッガのコマンド

(Debuggerモードの)debuggerバッファーでは、通常のEmacsコマンドに加えて、特別なコマンドが提供されます。デバッガでもっとも重要な使い方をするのは、制御フローを見ることができるコードをステップ実行するコマンドです。デバッガはインタープリターにより解釈された制御構造のステップ実行はできますが、バイトコンパイル済みの関数ではできません。バイトコンパイル済み関数をステップ実行したい場合は、同じ関数の解釈された定義に置き換えてください。(これを行なうには、その関数のソースをvisitして、関数の定義でC-M-xとタイプしてください。) プリミティブ関数のステップ実行にLispデバッガは使用できません。

以下はDebuggerモードのコマンドのリストです:

c

デバッガをexitして、実行を継続する。これはあたかもデバッガにエンターしなかったかのように(デバッガ内で行った変数値やデータ構造の変更などの副作用は除外される)、プログラムの実行を再開する。

d

実行を継続するが、次にLisp関数が何か呼び出されたときはデバッガにエンターする。これにより、ある式の下位の式をステップ実行して、下位の式が計算する値や、行うことを確認できる。

デバッガにエンターした関数呼び出しにたいして、この方法で作成されたスタックフレームには自動的にフラグがつくので、そのフレームをexitすると再びデバッガが呼び出されます。このフラグは、uコマンドを使用してキャンセルできます。

b

カレントフレームにフラグをつけるので、そのフレームをexitするときデバッガにエンターする。この方法でフラグがつけられたフレームは、backtraceバッファーでスターのマークがつく。

u

カレントフレームをexitしたとき、デバッガにエンターしてはならない。これは、そのフレームのbコマンドをキャンセルする。目に見える効果としては、backtraceバッファーの行からスターが削除される。

j

bと同じようにカレントフレームにフラグをつける。その後、cのように実行を継続するが、debug-on-entryによりセットアップされたすべての関数にたいするbreak-on-entryを一時的に無効にする。

e

ミニバッファーのLisp式を読み取り、(関連するlexical環境が適切なら)評価して、エコーエリアに値をプリントする。デバッガは特定の重要な変数とバッファーを処理の一部としてを変更する。eは一時的にデバッガの外部からそれらの値をリストアするので、それらを調べて変更できる。これによりデバッガはより透過的になる。対照的に、デバッガ内でM-:は特別なことを行わず、デバッガ内での変数の値を表示する。

R

eと同様だが、バッファー*Debugger-record*内の評価の結果も保存する。

q

デバッグされているプログラムを終了し、Emacsコマンド実行のトップレベルにリターンする。

C-gによりデバッガにエンターしたが、実際はデバッグではなくquitしたいときは、qコマンドを使用する。

r

デバッガから値をリターンする。ミニバッファーで式を読み取り、それを評価することにより、値が計算される。

dコマンドは、(bによるリクエスト、またはdによるそのフレームへのエンターによる)Lisp呼び出しフレームからのexitでデバッガが呼び出されたときに有用です。rコマンドで指定された値は、そのフレームの値として使用されます。これは、debugを呼び出して、そのリターン値を使用するときも有用です。それ以外は、rはcと同じ効果をもｙい、指定されたリターン値は問題になりません。

エラーによりデバッガにエンターしたときは、rコマンドは使用できません。

l

呼び出されたときにデバッガを呼び出す関数をリストします。これは、debug-on-entryによりエントリー時にbreakするようセットされた関数のリストです。

v

カレントスタックフレームのローカル変数の表示を切り替えます。

18.1.8 デバッガの呼び出し

以下では、デバッガを呼び出すために使用される関数debugの完全な詳細を説明します。

Command: debug &rest debugger-args

この関数は、デバッガにエンターします。この関数は*Backtrace*(デバッガへの2回目以降の再帰エントリーでは*Backtrace*<2>、...)という名前のバッファーにバッファーを切り替えて、Lisp関数呼び出しについての情報を書き込みます。それから再帰編集にエンターして、Debuggerモードでbacktraceバッファーを表示します。

Debuggerモードのコマンドc、d、j、rは再帰編集をexitします。その後、debugは以前のバッファーに戻って、debugを呼び出したものが何であれ、そこにリターンします。これは関数debugが呼び出し元にリターン可能な唯一の方法です。

debugger-argsを使用すると、debugは*Backtrace*の最上部に残りの引数を表示するもで、ユーザーがそれらを確認できます。以下で説明する場合を除き、これは、これらの引数を使用する唯一の方法です。

しかしdebugへの1つ目の引数にたいする値は、特別な意味をもちます。(これらの値は通常、debugを呼び出すプログラマーではなく、Emacs内部でのみ使用されます。) 以下はこれら特別な値のテーブルです:

lambda

1つ目の引数galambdaの場合、それはdebug-on-next-callが非nilのときに関数にエントリーしたことによりdebugが呼び出されたことを意味する。デバッガはバッファーのトップのテキスト行に‘Debugger entered--entering a function:’と表示する。

debug

1つ目の引数がdebugの場合、それはエントリー時にデバッグされるようにセットされた関数にエントリーしたことによりdebugが呼び出されたことを意味する。デバッガはlambdaのときと同様、‘Debugger entered--entering a function:’を表示します。これはその関数のスタックフレームもマークするので、exit時にデバッガが呼び出される。

t

1つ目の引数がtの場合、それはdebug-on-next-callが非nilのときに関数呼び出しの評価によりdebugが呼び出されたことを示す。デバッガはバッファーのトップの行に‘Debugger entered--beginning evaluation of function call form:’と表示する。

exit

1つ目の引数がexitのときは、exit時にデバッガを呼び出すよう以前にマークされたスタックフレームをexitしたことを示す。この場合は、debugに与えられた2つ目の引数が、そのフレームからリターンされた値になる。デバッガはバッファーのトップの行に‘Debugger entered--returning value:’とリターンされた値を表示する。

error

1つ目の引数がerrorのときは、ハンドルされていないエラーまたはquitがシグナルされてデバッガにエンターした場合で、デバッガは‘Debugger entered--Lisp error:’とその後にシグナルされたエラーおよびsignalへの引数を表示して、それを示す。たとえば、

(let ((debug-on-error t))
  (/ 1 0))

------ Buffer: *Backtrace* ------
Debugger entered--Lisp error: (arith-error)
  /(1 0)
...
------ Buffer: *Backtrace* ------

エラーがシグナルされた場合はおそらく、変数debug-on-errorは非nilで、quitがシグナルされた場合はおそらく、変数debug-on-quitは非nilである。

nil

明示的にデバッガにエンターしたいときは、debugger-argsの1つ目の引数にnilを使用する。残りのdebugger-argsは、バッファーのトップの行にプリントされる。メッセージ — たとえばdebugが呼び出された条件を思い出すためのリマインダー — の表示にこの機能を使用できる。

18.1.9 デバッガの内部

このセクションでは、デバッガ内部で使用される関数と変数について説明します。

Variable: debugger

この関数の値は、デバッガを呼び出す関数呼び出しです。値には任意個の引数をとる関数、より具体的には関数の名前でなければなりません。この関数は何らかのデバッガを呼び出すべきです。この変数のデフォルト値はdebugです。

関数にたいしてLispが渡す1つ目の引数は、その関数がなぜ呼び出されたかを示します。引数の慣習は、debug(デバッガの呼び出し)に詳解されています。

Function: backtrace

この関数は現在アクティブなLisp関数呼び出しのトレースをプリントします。この関数はdebugが*Backtrace*バッファーに書き込む内容を得るために使用されます。どの関数呼び出しがアクティブか判断するためにスタックにアクセスしなければならないので、この関数はCで記述されています。リターン値は、常にnilです。

以下の例では、Lisp式で明示的にbacktraceを呼び出しています。これはストリームstandard-output(この場合はバッファー‘backtrace-output’)にbacktraceをプリントします。

backtraceの各行は、1つの関数呼び出しを表します。関数の引数が既知の場合は行に値が表示され、まだ計算中の場合は行にその旨が示されます。スペシャルフォームの引数は無視されます。

(with-output-to-temp-buffer "backtrace-output"
  (let ((var 1))
    (save-excursion
      (setq var (eval '(progn
                         (1+ var)
                         (list 'testing (backtrace))))))))

     ⇒ (testing nil)

----------- Buffer: backtrace-output ------------
  backtrace()
  (list ...computing arguments...)

  (progn ...)
  eval((progn (1+ var) (list (quote testing) (backtrace))))
  (setq ...)
  (save-excursion ...)
  (let ...)
  (with-output-to-temp-buffer ...)
  eval((with-output-to-temp-buffer ...))
  eval-last-sexp-1(nil)

  eval-last-sexp(nil)
  call-interactively(eval-last-sexp)
----------- Buffer: backtrace-output ------------

User Option: debugger-stack-frame-as-list

If this variable is non-nil, every stack frame of the backtrace is displayed as a list. This aims at improving the backtrace readability at the cost of special forms no longer being visually different from regular function calls.

With debugger-stack-frame-as-list non-nil, the above example would look as follows:

----------- Buffer: backtrace-output ------------
  (backtrace)
  (list ...computing arguments...)

  (progn ...)
  (eval (progn (1+ var) (list (quote testing) (backtrace))))
  (setq ...)
  (save-excursion ...)
  (let ...)
  (with-output-to-temp-buffer ...)
  (eval (with-output-to-temp-buffer ...))
  (eval-last-sexp-1 nil)

  (eval-last-sexp nil)
  (call-interactively eval-last-sexp)
----------- Buffer: backtrace-output ------------

Variable: debug-on-next-call

この変数が非nilの場合、それは次のeval、apply、funcallの前にデバッガを呼び出すよう指定します。デバッガへのエンターにより、debug-on-next-callはnilにセットされます。

デバッガのdコマンドは、この変数をセットすることにより機能します。

Function: backtrace-debug level flag

この関数は、そのスタックフレームのlevel下位のスタックフレームのdebug-on-exitフラグにflagに応じた値をセットします。flagが非nilの場合は、後にそのフレームをexitするときデバッガにエンターします。そのフレームを通じた非ローカルexitでも、デバッガにエンターします。

この関数は、デバッガだけに使用されます。

Variable: command-debug-status

この変数はカレントのインタラクティブコマンドのデバッグ状態を記録します。コマンドがインタラクティブに呼び出されるたびに、この変数はnilにバインドされます。デバッガは、同じコマンドが呼び出されたときのデバッガ呼び出しに情報を残すために、この変数をセットできます。

普通のグローバル変数ではなくこの変数を使用する利点は、そのデータが後続のコマンド呼び出しに決して引き継がれないことです。

This variable is obsolete and will be removed in future versions.

Function: backtrace-frame frame-number &optional base

関数backtrace-frameは、Lispデバッガ内での使用を意図しています。これは、frame-numberレベル下位のスタックフレームで、何の評価が行われているかに関する情報をリターンします。

そのフレームがまだ引数を評価していない場合、またはそのフレームがスペシャルフォームの場合、値は(nil function arg-forms…)です。

そのフレームが引数を評価して関数をすでに呼び出した場合、リターン値は(t function arg-values…)です。

リターン値のfunctionは何であれ評価されたリストのCARとして提供されます。マクロ呼び出しの場合はlambda式になります。その関数に&rest引数がある場合は、リストarg-valuesの末尾に表されます。

If base is specified, frame-number counts relative to the topmost frame whose function is base.

frame-numberが範囲外の場合、backtrace-frameはnilをリターンします。

Function: mapbacktrace function &optional base

The function mapbacktrace calls function once for each frame in the backtrace, starting at the first frame whose function is base (or from the top if base is omitted or nil).

function is called with four arguments: evald, func, args, and flags.

If a frame has not evaluated its arguments yet or is a special form, evald is nil and args is a list of forms.

If a frame has evaluated its arguments and called its function already, evald is t and args is a list of values. flags is a plist of properties of the current frame: currently, the only supported property is :debug-on-exit, which is t if the stack frame’s debug-on-exit flag is set.

18.2 Edebug

EdebugはEmacs Lispプログラムにたいするソースレベルデバッガです。これにより、以下のことができます:

式の前や後でストップして、評価をステップで実行する。
条件付き、または無条件のbreakpointのセット。
指定された条件がtrueのときにストップする(グローバルbreakpoint)。
ストップポイントごとに停止したり、breakpointごとに簡単に停止して、低速または高速にトレースを行う。
Edebug外部であるかのように、式の結果を表示し、式を評価する。
式のリストを自動的に再評価して、Edebugがディスプレイを更新するたびにそれらの結果を表示する。
関数呼び出しとリターンのトレース情報を出力する。
エラー発生時にストップする。
Edebug自身のフレームを除外してbacktraceを表示する。
マクロおよびフォームの定義で引数の評価を指定する。
初歩的なカバレッジテストと頻度数の取得。

以下の初めの3つのセクションは、使用を開始するためにEdebugについて十分説明します。

18.2.1 Edebugの使用		Edebug使用のための手引き。
18.2.2 Edebugのためのインストルメント		Edebugでデバッグするために、コードをインストルメント(計装)しなければならないe
18.2.3 Edebugの実行モード		多かれ少なかれ、ストップする実行モード。
18.2.4 ジャンプ		特定の位置にジャンプするコマンド。
18.2.5 その他のEdebugコマンド		さまざまなコマンド。
18.2.6 ブレーク		プログラムをストップさせるbreakpointのセット。
18.2.7 エラーのトラップ		Edebugでのエラーのトラップ。
18.2.8 Edebugのビュー		Edebugの内側と外側のビュー。
18.2.9 評価		Edebugでの式の評価。
18.2.10 評価 List Buffer		Edebugにエンターするたびに値が表示される式。
18.2.11 Edebugでのプリント		プリントのカスタマイズ。
18.2.12 トレースバッファー		バッファー内で採れを生成する方法。
18.2.13 カバレッジテスト		評価をカバレッジテストする方法。
18.2.14 コンテキスト外部		Edebugが保存およびリストアするデータ。
18.2.15 Edebugとマクロ		マクロ呼び出しをハンドルする方法の指定。
18.2.16 Edebugのオプション		Edebugをカスタマイズするオプション変数。

18.2.1 Edebugの使用

EdebugでLispプログラムをデバッグするには、最初にデバッグしたいLispコードをインストルメント(instrument: 計装)しなければなりません。これを行なうもっともシンプルな方法は、関数またはマクロの定義に移動して、C-u C-M-x(プレフィクス引数を指定したeval-defun)を行います。コードをインストルメントする他の手段については、Edebugのためのインストルメントを参照してください。

一度関数をインストルメントすると、その関数にたいする任意の呼び出しにより、Edebugがアクティブになります。Edebugがアクティブになると、どのEdebug実行モードを選択したかに依存して、その関数をステップ実行できるように実行がストップされるか、ディスプレイを更新してデバッグコマンドにたいするチェックの間、実行が継続されます。デフォルトの実行モードstepで、これは実行をストップします。Edebugの実行モードを参照してください。

Edebugでは通常、デバッグしているLispコードをEmacsバッファーで閲覧します。これをソースコードバッファー(source code buffer)と呼び、バッファーは一時的に読み取り専用になります。

左フリンジの矢印は、その関数で実行されている行を示します。最初ポイントはその関数の実行されている行にありますが、ポイントを移動するとこれは真ではなくなります。

以下は、facの定義(以下を参照)をインストルメントして(fac 3)を実行した場合に通常目にするものです。ポイントは、ifの前の開きカッコにあります。

(defun fac (n)
=>∗(if (< 0 n)
      (* n (fac (1- n)))
    1))

関数内でEdebugが実行をストップできる位置のことを、ストップポイント(stop points)と呼びます。ストップポイントは、リストであるような部分式の前後、および変数参照の後でも発生します。以下は、関数fac内のストップポイントをピリオドで示したものです:

(defun fac (n)
  .(if .(< 0 n.).
      .(* n. .(fac .(1- n.).).).
    1).)

Emacs Lispモードのコマンドに加えて、ソースコードバッファーでは、Edebugのスペシャルコマンドが利用できます。たとえば、EdebugコマンドSPCで次のストップポイントまで実行することができます。facにエントリーした後に一度facとタイプした場合は、以下のように表示されるでしょう:

(defun fac (n)
=>(if ∗(< 0 n)
      (* n (fac (1- n)))
    1))

式の後でEdebugが実行をストップしたときは、エコーエリアにその式の値が表示されます。

他にも頻繁に使用されるコマンドとして、ストップポイントにbreakpointをセットするb、breakpointに達するまで実行するg、Edebugをexitしてトップレベルのコマンドループにリターンするqがあります。また、?とタイプするとすべてのEdebugコマンドがリストされます。

18.2.2 Edebugのためのインストルメント

LispコードのデバッグにEdebugを使用するためには、最初にそのコードをインストルメント(instrument: 計装)しなければなりません。コードをインストルメントすると、適切な位置でEdebugを呼び出すために追加コードが挿入されます。

関数定義でプレフィクス引数とともにコマンドC-M-x (eval-defun)を呼び出すと、それを評価する前にその定義をインストルメントします。(ソースコード自体は変更しません。) 変数edebug-all-defsが非nilの場合は、プレフィクス引数の意味を反転します。この場合、C-M-xはプレフィクス引数がなければその定義をインストルメントします。edebug-all-defsのデフォルト値はnilです。コマンドM-x edebug-all-defsは、変数edebug-all-defsの値を切り替えます。

edebug-all-defsが非nilの場合はeval-region、eval-current-buffer、eval-bufferも、それらが評価する定義をインストルメントします。同様に、edebug-all-formsは、eval-regionが(非定義フォームさえ含む）あらゆるフォームをインストルメントすべきかを制御します。これはミニバッファー内でのロードや評価には適用されません。コマンドM-x edebug-all-formsは、このオプションを切り替えます。

他にもコマンドM-x edebug-eval-top-level-formが利用可能で、これはedebug-all-defsやedebug-all-formsの値に関わらず、トップレベルの任意のフォームをインストルメントします。edebug-defunはedebug-eval-top-level-formのエイリアスです。

Edebugがアクティブのの間、コマンドI(edebug-instrument-callee)は、ポイント後のリストフォームに呼び出される関数およびマクロ定義がまだインストルメントされていなければ、それらをインストルメントします。これは、そのファイルのソースの場所をEdebugが知っている場合だけ可能です。この理由によりEdebugロード後は、たとえ評価する定義をインストルメントしない場合でも、eval-regionは評価するすべての定義の位置を記録します。インストルメント済み関数呼び出しにステップインするiコマンド(ジャンプを参照)も参照してください。

Edebugはすべての標準スペシャルフォーム、式引数をもつinteractiveフォーム、無名ラムダ式、およびその他の定義フォームのインストルメント方法を知っています。しかし、Edebugはユーザー定義マクロが引数にたいして何を行うかを判断できないので、Edebug仕様を使用してその情報を与えなければなりません。詳細はEdebugとマクロを参照してください。

Edebugがセッション内で最初にコードをインストルメントしようとするときは、フックedebug-setup-hookを実行してから、それにnilをセットします。使おうとしているパッケージに結びつけてEdebug仕様をロードするためにこれを使用できますが、それはEdebugを使用するときだけ機能します。

If Edebug detects a syntax error while instrumenting, it leaves point at the erroneous code and signals an invalid-read-syntax error. Example:

error→ Invalid read syntax: "Expected lambda expression"

One potential reason for such a failure to instrument is that some macro definitions are not yet known to Emacs. To work around this, load the file which defines the function you are about to instrument.

定義からインストルメントを削除するには、単にインストルメントを行わない方法でその定義を再評価するだけです。フォームを絶対にインストルメントせずに評価するには、2つの方法があります。それはファイルからのloadによる評価と、ミニバッファーからのeval-expression(M-:)による評価です。

Edebug内で利用可能な他の評価関数については、評価を参照してください。

18.2.3 Edebugの実行モード

Edebugは、デバッグするプログラムの実行にたいして、いくつかの実行モードをサポートします。これらの実行モードを、Edebug実行モード(Edebug execution modes)と呼びます。これらをメジャーモードやマイナーモードと混同しないでください。カレントのEdebug実行モードは、プログラムをストップする前にEdebugがどれだけ実行を継続するか — たとえばストップポイントごとにストップ、あるいは次のbreakpointまで継続など — と、ストップする前にEdebugがどれだけ進捗を表示するかを決定します。

Edebug実行モードは通常、ある特定のモードでプログラムを継続させるコマンドをタイプすることにより指定します。以下は、それらのコマンドのテーブルです。プログラムの実行を再開S以外は、少なくともある長さの間だけ実行を継続します。

S: Stop(ストップ): これ以上プログラムを実行しないで、Edebugのコマンドを待つ(edebug-stop)。
SPC: Step(ステップ): 次のストップポイントでストップする(edebug-step-mode)。
n: Next(次へ): 式の後にある次のストップポイントでストップする(edebug-next-mode)。ジャンプのedebug-forward-sexpも参照。
t: Trace(トレース): Edebugのストップポイントごとにpause(通常は1秒)する(edebug-trace-mode)。
T: Rapid trace(高速でトレース):ストップポイントごとに表示を更新するが、実際にpauseはしない(edebug-Trace-fast-mode)。
g: Go(進む): 次のbreakpointまで実行する(edebug-go-mode)。Edebugのブレークポイントを参照。
c: Continue(継続): breakpointごとにpauseしてから継続する(edebug-continue-mode)。
C: Rapid continue(高速で継続): ポイントを各breakpointへ移動するが、pauseしない(edebug-Continue-fast-mode)。
G: Go non-stop(ストップせず進む): breakpointを無視する(edebug-Go-nonstop-mode)。まだS、またはその他の編集コマンドでプログラムをストップするのは可能。

一般的に、上記リストの最初のほうにある実行モードは後のほうの実行モードに比べて、プログラムをより低速に実行、またはすぐにストップさせます。

When you enter a new Edebug level, Edebug will normally stop at the first instrumented function it encounters. If you prefer to stop only at a break point, or not at all (for example, when gathering coverage data), change the value of edebug-initial-mode from its default step to go, or Go-nonstop, or one of its other values (see section Edebugのオプション). You can do this readily with C-x C-a C-m (edebug-set-initial-mode):

Command: edebug-set-initial-mode: This command, bound to C-x C-a C-m, sets edebug-initial-mode. It prompts you for a key to indicate the mode. You should enter one of the eight keys listed above, which sets the corresponding mode.

Note that you may reenter the same Edebug level several times if, for example, an instrumented function is called several times from one command.

実行中、またはトレース中は、任意のEdebugコマンドをタイプすることにより、実行をインタラプト(interrupt: 中断、割り込み)できます。Edebugは次のストップポイントでプログラムをストップしてから、タイプされたコマンドを実行します。たとえば、実行中にtをタイプすると、次のストップポイントでトレースモードに切り替えます。Sを使用すれば、他に何も行わずに実行をストップできます。

関数でたまたま読み取り入力が発生した場合には、実行のインタラプトを意図してタイプされた文字は、かわりにその関数により読み取られます。そのプログラムが入力を欲するタイミングに注意を払うことで、そのような意図せぬ結果を避けることができます。

このセクションのコマンドを含むキーボードマクロは、完全には機能しません。プログラムを再開するためにEdebugからexitすると、キーボードマクロの追跡記録は失われます。これを処理するのは、簡単ではありません。またEdebug外部でキーボードマクロを定義または実行しても、Edebug内部のコマンドに影響しません。通常これは利点です。Edebugのオプション内のedebug-continue-kbd-macroオプションも参照してください。

User Option: edebug-sit-for-seconds: このオプションは、traceモードおよびcontinueモードで実行ステップの間を何秒待つか指定します。デフォルトは1秒です。

18.2.4 ジャンプ

このセクションで説明するコマンドは、指定された場所に達するまで実行を続けます。iを除くすべてのコマンドは、ストップ場所を確立するために一時的なbreakpointを作成してから、goモードにスイッチします。意図されたストップポイントの前にある他のストップポイントに達した場合も、実行はストップします。breakpointの詳細は、Edebugのブレークポイントを参照してください。

これらのコマンドは、非ローカルexitの場合はプログラムのストップを期待する一時的なbreakpointをバイパスできるので、期待どおり機能しないかもしれません。

h: ポイントがある場所の近くのストップポイントへ実行を進める(edebug-goto-here)。
f: プログラムの式を1つ分実行する(edebug-forward-sexp)。
o: sexpを含む終端までプログラムを実行する(edebug-step-out)。
i: ポイントの後のフォームから呼び出された関数またはマクロにステップインする(edebug-step-in)。

hコマンドは一時的なbreakpointを使用して、ポイントのカレント位置、またはその後のストップポイントまで処理を進めます。

fコマンドは式を1つ飛び越してプログラムを実家します。より正確には、forward-sexpにより到達できる位置に一時的なbreakpointをセットしてからgoモードで実行するので、プログラムはそのbreakpointでストップすることになります。

プレフィクス引数nとともに使用した場合は、ポイントからn個のsexp(s-expression: S式)を超えた場所に一時的なbreakpointをセットします。ポイントを含むリストがnより少ない要素で終わるような場合は、ストップ箇所はポイントが含まれる式の後になります。

forward-sexpが見つける位置と、プログラムを実際にストップさせたい位置なのかチェックしなければなりません。たとえばcond内では、これは正しくないかもしれません。

fコマンドは柔軟性を与えるために、forward-sexpをストップポイントではなく、ポイント位置から開始します。カレントのストップポイントから1つの式を実行したい場合は、まずそこにポイントを移動するためにw(edebug-where)をタイプして、それからfをタイプしてください。

The o command continues out of an expression. It places a temporary breakpoint at the end of the sexp containing point. If the containing sexp is a function definition itself, o continues until just before the last sexp in the definition. If that is where you are now, it returns from the function and then stops. In other words, this command does not exit the currently executing function unless you are positioned after the last sexp.

Normally, the h, f, and o commands display “Break” and pause for edebug-sit-for-seconds before showing the result of the form just evaluated. You can avoid this pause by setting edebug-sit-on-break to nil. See section Edebugのオプション.

iコマンドは、ポイントの後のリストフォームに呼び出された関数、またはマクロにステップインします。そのフォームは、評価されようとしているもの1つである必要はないことに注意してください。しかし、そのフォームが評価されようとしている関数呼び出しの場合は、引数が何も評価されないうちにこのコマンドを使用しないと、遅すぎることを覚えておいてください。

iコマンドは、ステップインしようとしている関数またはマクロがまだインストルメントされていない場合は、それらをインストルメントします。これは便利かもしれませんが、それらを明示的に非インストルメントしない場合、その関数またはマクロはインストルメントされたままになることを覚えておいてください。

18.2.5 その他のEdebugコマンド

ここでは、その他のEdebugコマンドを説明します。

?

Edebugのヘルプメッセージを表示する(edebug-help)。

C-]

1レベルを中断して以前のコマンドレベルへ戻る(abort-recursive-edit)。

q

エディターのトップレベルのコマンドループにリターンする(top-level)。これは、すべてのレベルのEdebugアクティビティを含む、すべての再帰編集レベルをexitする。しかし、フォームunwind-protectまたはcondition-caseで保護されたインストルメント済みのコードはデバッグを再開するかもしれない。

Q

qと同様だが、保護されたコードでもストップしない(edebug-top-level-nonstop)。

r

エコーエリアに、もっとも最近の既知のコマンドを再表示する(edebug-previous-result)。

d

backtraceを表示するが、明確であるようにEdebug自身の関数は除外される(edebug-backtrace)。

Edebugのbacktraceバッファーでは、標準デバッガ内のようにバッガコマンドは使用できない。

実行を継続したとき、backtraceバッファーは自動的にkillされる。

Edebugから再帰的にEdebugをアクティブにするコマンドを呼び出すことができます。Edebugがアクティブなときは常に、qによトップレベルの終了、またはC-]による再帰編集1レベルの中断ができます。dにより、すべての未解決な評価のbacktraceを表示できます。

18.2.6 ブレーク

Edebugのstepモードは、次のストップポイントに達したときに、実行をストップします。一度開始されたEdebugの実行をストップするには、他に3つの方法があります。それはbreakpoint、グローバルbreak条件、およびソースbreakpointです。

18.2.6.1 Edebugのブレークポイント

Edebugを使用しているときは、テスト中のプログラム内にbreakpointを指定できます。breakpointとは、実行がストップされる場所のことです。Edebugの使用で定義されている任意のストップポイントに、breakpointをセットできます。breakpointをセットおよび解除において影響を受けるストップポイントは、ソースコードバッファー内でポイント位置、またはポイント位置の後の最初のストップポイントです。以下はEdebugのbreakpoint用のコマンドです:

b: ポイント位置、またはポイント位置の後のストップポイントに、breakpointをセットする(edebug-set-breakpoint)。プレフィクス引数を使用した場合、それは一時的なbreakpointになり、プログラムが最初にそこで停止したとき解除される。
u: (もしあれば)ポイント位置、またはポイント位置の後のストップポイントにあるbreakpointを解除(unset)する(edebug-unset-breakpoint)。
x condition RET: conditionを評価して非nil値になる場合だけプログラムをストップする、条件付きbreakpointをセットする(edebug-set-conditional-breakpoint)。プレフィクス引数を指定した場合は、一時的なbreakpointになる。
B: カレント定義内の、次のbreakpointにポイントを移動する(edebug-next-breakpoint)。

Edebug内では、bでbreakpointをセットして、uでそれを解除できます。最初に望ましいストップポイントにポイントを移動してから、そこにbreakpointをセットまたは解除するためにbまたはuをタイプしますbreakpointがない場所でbreakpointを解除しても、影響はありません。

ある定義を再評価、または再インストルメントすると、以前のbreakpointはすべて削除されます。

条件付きbreakpoint(conditional breakpoint)は、プログラムがそこに達するたびに条件をテストします。条件を評価した結果エラーが発生した場合、エラーは無視され結果はnilになります。条件付きbreakpointをセットするにはxを使用して、ミニバッファーで条件式を指定します。以前にセットされた条件付きbreakpointがあるストップポイントに条件付きbreakpointをセットすると、以前の条件式がミニバッファーに配されるので、それを編集できます。

プレフィクス引数を指定してbreakpointをセットするコマンドを使用することにより、一時的な条件付きbreakpoint、および無条件のbreakpointを作成できます。一時的なbreakpointによりプログラムがストップしたとき、そのbreakpointは自動的に解除されます。

Go-nonstopモードを除き、Edebugは常にbreakpointでストップ、またはpauseします。Go-nonstopモードでは、breakpointは完全に無視されます。

breakpointがどこにあるか探すには、Bコマンドを使用します。このコマンドは同じ関数内から、ポイント以降にある次のbreakpoint(ポイント以降にbreakpointが存在しない場合は最初のbreakpoint)にポイントを移動します。このコマンドは実行を継続せず、単にバッファー内のポイントを移動します。

18.2.6.2 グローバルなブレーク条件

グローバルbreak条件(global break condition)は指定された条件が満たされたとき、それがどこで発生したかによらず、実行をストップします。Edebugは、すべてのストップポイントでグローバルbreak条件を評価します。これが非nil値に評価された場合は、あたかもそのストップポイントにbreakpointがあったかのように、実行をストップまたはpauseします(実行モードによる)。条件の評価でエラーを取得した場合は、実行をストップしません。

条件式はedebug-global-break-conditionに格納されます。EdebugがアクティブなときにソースバッファーからXコマンドを使用するか、Edebugがロードされている間は任意のバッファーから任意のタイミングでC-x X X(edebug-set-global-break-condition)を使用することにより新たな式を指定できます。

グローバルbreak条件は、コード内のどこでイベントが発生したかを見つけるもっともシンプルな方法ですが、コードの実行は遅くなります。そのため、使用しないときは条件をnilにリセットするべきです。

18.2.6.3 ソースブレークポイント

定義内のすべてのbreakpointは、それをインストルメントするたびに失われます。breakpointが失われないようにしたい場合は、ソースコード内で単に関数edebugを呼び出すソースbreakpoint(source breakpoint)を記述できます。もちろん、そのような呼び出しを条件付きすることにもできます。たとえばfac関数内に以下のような行を1行目に挿入して、引数が0になったときストップさせることができます:

(defun fac (n)
  (if (= n 0) (edebug))
  (if (< 0 n)
      (* n (fac (1- n)))
    1))

facの定義がインストルメントされて呼び出されたとき、edebug呼び出しはbreakpointとして振る舞います。実行モードに応じて、Edebugはそこでストップまたはpauseします。

edebugが呼び出されたときにインストルメント済みのコードが実行されていなければ、この関数はdebugを呼び出します。

18.2.7 エラーのトラップ

エラーがシグナルされて、それがcondition-caseでハンドルされていないとき、Emacsは通常エラーメッセージを表示します。Edebugがアクティブでインストルメント済みのコードを実行中は、ハンドルされていないエラーには通常Edebugが対応します。オプションedebug-on-errorおよびedebug-on-quitで、これをカスタマイズできます。Edebugのオプションを参照してください。

Edebugがエラーに対応するときは、エラー発生箇所の前にある最後のストップポイントを表示します。この場所はインストルメントされていない関数の呼び出しで、その関数内で実際にエラーが発生したのかもしれません。バインドされていない変数に関するエラーの場合は、最後の既知のストップポイントは、その不正な変数参照から遠く離れた場所かもしれません。そのような場合は、完全なbacktraceを表示したいと思うでしょう(その他のEdebugコマンドを参照)。

Edebugがアクティブの間にdebug-on-error、またはdebug-on-quitを変更した場合、それらの変更はEdebugが非アクティブになったとき失われます。さらに、Edebugの再帰編集の間、これらの変数はEdebugの外部でもっていた値にバインドされます。

18.2.8 Edebugのビュー

これらのEdebugコマンドは、Edebugにエントリーする前のバッファーの外観と、ウィンドウの状態を調べるコマンドです。外部のウィンドウ構成は、ウィンドウのコレクションとその内容であり、これらは実際にEdebugの外部にあります。

v

外部のウィンドウ構成ビューに切り替える(edebug-view-outside)。Edebugにリターンするには、C-x X wをタイプする。

p

一時的に外部のカレントバッファーを表示し、ポイントもその外部の位置になる(edebug-bounce-point)。Edebugにリターンする前に、1秒pauseする。プレフィクス引数nを指定すると、かわりにn秒pauseする。

w

ソースコードバッファー内のカレントストップポイントにポイントを戻す(edebug-where)。

このコマンドを同じバッファーを表示する異なるウィンドウで使用した場合には、そのウィンドウは将来カレント定義を表示するために代用される。

W

Edebugが外部のウィンドウ構成を保存、およびリストアするかどうかを切り替える(edebug-toggle-save-windows)。

プレフィクス引数を指定すると、Wは選択されたウィンドウの保存とリストアだけを切り替える。ソースコードバッファーを表示していないウィンドウを指定するには、グローバルキーマップからC-x X Wを使用しなければならない。

v、または単にpでカレントバッファーにポイントを反跳させれば、たとえ通常は表示されないウィンドウでも、外部のウィンドウ構成を調べることができます。

ポイントを移動した後に、ストップポイントに戻りたいときがあるかもしれません。これは、ソースコードバッファーからwで行うことができます。どのバッファーにいても、C-x X wを使用すれば、ソースコードバッファー内のストップポイントに戻ることができます。

保存をオフにするためにWを使用するたびに、Edebugは外部のウィンドウ構成を忘れます。そのため、たとえ保存をオンに戻しても、(プログラムを実行することにより)次にEdebugをexitしたとき、カレントウィンドウ構成は変更されないまま残ります。しかし、十分な数のウィンドウをオープンしていない場合は、*edebug*と*edebug-trace*の再表示が、あなたが見たいバッファーと競合するかもしれません。

18.2.9 評価

Edebug内では、まるでEdebugが実行されていないかのように、式を評価できます。式の評価とプリントに際して、Edebugが不可視になるよう試みます。。副作用をもつ式の評価は、Edebugが明示的に保存とリストアを行うデータへの変更を除き、期待したとおり機能するでしょう。このプロセスの詳細は、コンテキスト外部を参照してください。

e exp RET: Edebugのコンテキスト外で、式expを評価する(edebug-eval-expression)。つまり、Edebugはその式への干渉を最小限にしようと努める。
M-: exp RET: Edebug自身のコンテキスト内で、式expを評価する(eval-expression)。
C-x C-e: Edebugのコンテキスト外で、ポイントの前の式を評価する(edebug-eval-last-sexp)。

Edebugは、cl.el内の構文(lexical-let、macrolet、symbol-macrolet)により作成された、レキシカル(lexical)にバインドされたシンボルへの参照を含む式の評価をサポートします。

18.2.10 評価 List Buffer

式をインタラクティブに評価するために、*edebug*と呼ばれる評価リストバッファー(evaluation list buffer)を使用できます。Edebugがディスプレイを更新するたびに自動的に評価される、式の評価リスト(evaluation list)もセットアップできます。

E: 評価リストバッファー*edebug*に切り替える(edebug-visit-eval-list)。

*edebug*バッファーでは、以下の特別なコマンドと同様に、Lisp Interactionモード(see Lisp Interaction in The GNU Emacs Manual)のコマンドも使用できます。

C-j: ポイントの前の式をコンテキスト外で評価して、その値をバッファーに挿入する(edebug-eval-print-last-sexp)。
C-x C-e: Edebugのコンテキスト外で、ポイントの前の式を評価する(edebug-eval-last-sexp)。
C-c C-u: バッファー内のコンテンツから、新たに評価リストを構築する(edebug-update-eval-list)。
C-c C-d: ポイントのある評価リストグループを削除する(edebug-delete-eval-item)。
C-c C-w: ソースコードバッファーに切り替えてカレントストップポイントに戻る(edebug-where)。

評価リストウィンドウ内では、*scratch*にいるときと同様に、C-jやC-x C-eで式を評価できますが、それらはEdebugのコンテキスト外で評価されます。

インタラクティブに入力した式(とその結果)は、実行を継続すると失われます。しかし、実行がストップされるたびに評価されるように、式から構成される評価リストをセットアップできます。

これを行なうには、評価リストバッファー内で1つ以上の評価リストグループ(evaluation list group)を記述します。評価リストグループは、1つ以上のLisp式から構成されます。グループはコメント行で区切られます。

コマンドC-c C-u(edebug-update-eval-list)は、バッファーをスキャンして各グループの最初の式を使用して、評価リストを再構築します。(これはグループの2つ目の式は以前に計算、表示されている値だという発想からです。)

Edebugにエントリーするたびに、評価リストの各式(および式の後に式のカレント値)をバッファーに挿入して再表示します。これはコメント行も挿入するため、各式はそのグループの一員となります。したがって、バッファーのテキストを変更せずにC-c C-uとタイプした場合、評価リストは実際には変更されません。

評価リストからの評価の間にエラーが発生した場合、それが式の結果であるかのようにエラーメッセージが文字列で表示されます。したがって、カレントで無効な変数を使用する式により、デバッグが中断されることはありません。

以下は、いくつかの式を評価リストウィンドウに追加したとき、どのように見えるかの例です:

(current-buffer)
#<buffer *scratch*>
;---------------------------------------------------------------
(selected-window)
#<window 16 on *scratch*>
;---------------------------------------------------------------
(point)
196
;---------------------------------------------------------------
bad-var
"Symbol's value as variable is void: bad-var"
;---------------------------------------------------------------
(recursion-depth)
0
;---------------------------------------------------------------
this-command
eval-last-sexp
;---------------------------------------------------------------

グループを削除するには、グループ内にポイントを移動してC-c C-dをタイプするか、単にグループのテキストを削除してC-c C-uで評価リストを更新します。評価リストに新たな式を追加するには、適切な箇所にその式を挿入し、新たなコメント行を挿入してからC-c C-uをタイプします。コメント行にダッシュを挿入する必要はありません — 内容は関係ないのです。

*edebug*を選択した後に、C-c C-wでソースコードバッファーにリターンできます。*edebug*は実行を継続したときkillされ、次回必要なとき再作成されます。

18.2.11 Edebugでのプリント

プログラム内の式が循環リスト構造(circular list structure)を含む値を生成する場合は、Edebugがそれをプリントしようとしたときエラーとなるかもしれません。

循環構造への対処の1つに、print-lengthおよびprint-levelにプリントの切り詰めをセットする方法があります。Edebugは、変数edebug-print-lengthおよびedebug-print-levelの値(非nil値をもつ場合)を、これらの変数にバインドします。出力に影響する変数を参照してください。

User Option: edebug-print-length: 非nilの場合は、結果をプリントするときEdebugはprint-lengthをこの値にバインドする。デフォルト値は50。

User Option: edebug-print-level: 非nilの場合は、結果をプリントするときEdebugはprint-levelをこの値にバインドする。デフォルト値は50。

print-circleを非nil値にバインドして、循環構造や要素を共有する構造を、より参考になる情報をプリントすることもできます。

以下は循環構造を作成するコードの例です:

(setq a '(x y))
(setcar a a)

カスタムプリントはこれを、‘Result: #1=(#1# y)’のようにプリントします。‘#1=’という表記はその後の構造をラベル‘1’とラベル付けし、‘#1#’表記はその前にラベル付けされた構造を参照しています。この表記は、リストやベクターの任意の共有要素に使用されます。

User Option: edebug-print-circle: 非nilの場合は、結果をプリントするときEdebugはprint-circleをこの値にバインドする。デフォルト値はt。

他にプログラムもカスタムプリントを使用できます。詳細はcust-print.elを参照してください。

18.2.12 トレースバッファー

Edebugは実行トレースを*edebug-trace*という名前のバッファーに格納して記録できます。実行トレースとは関数呼び出しよリターンのログのことで、関数名と引数、および値が確認できます。トレースレコードを有効にするには、edebug-traceを非nil値にセットしてください。

トレースバッファーの作成は、実行モードのトレースの使用(Edebugの実行モードを参照)と同じではありません。

トレースレコードが有効なときは、関数へのエントリーとexitのたびに、トレースバッファーに行が追加されます。関数エントリーレコードは‘::::{’、および関数名と引数の値により構成されます。関数exitレコードは‘::::}’、および関数名と関数の結果により構成されます。

‘:’の数は、関数エントリーの再帰レベルを表します。トレースバッファーでは、関数呼び出しの開始と終了の検索に‘{’と‘}’を使用できます。

関数edebug-print-trace-beforeおよびedebug-print-trace-afterを再定義することにより、関数エントリーと関数exitのトレースレコードをカスタマイズできます。

Macro: edebug-tracing string body…: このマクロはbodyフォーム実行活動にたいする、追加のトレース情報をリクエストする。引数stringは、トレースバッファーに配す‘{’または‘}’の後のテキストを指定する。すべての引数は評価され、edebug-tracingはbody内の最後のフォームの値をリターンする。

Function: edebug-trace format-string &rest format-args: この関数は、トレースバッファーにテキストを挿入する。テキストは、(apply 'format format-string format-args)により計算される。エントリー間の区切りとして改行も付け加える。

edebug-tracingおよびedebug-traceは、たとえEdebugが非アクティブでも、呼び出されたときは常にトレースバッファーに行を挿入します。トレースバッファーへのテキストの追加により、挿入された最後の行が見えるようにウィンドウもスクロールします。

18.2.13 カバレッジテスト

Edebugは基本的なカバレッジテスト(coverage test)と実行頻度(execution frequency)の表示を提供します。

Coverage testing works by comparing the result of each expression with the previous result; each form in the program is considered covered if it has returned two different values since you began testing coverage in the current Emacs session. Thus, to do coverage testing on your program, execute it under various conditions and note whether it behaves correctly; Edebug will tell you when you have tried enough different conditions that each form has returned two different values.

カバレッジテストにより実行速度が低下するので、edebug-test-coverageが非nilのときだけカバレッジテストが行なわれます。頻度計数(frequency count)は、たとえ実行モードがGo-nonstopでも、カバレッジテストが有効か無効かに関わらず、すべての式にたいして処理されます。

定義にたいするカバレッジ情報と頻度数の両方を表示するには、C-x X =(edebug-display-freq-count)を使用する。単に=(edebug-temp-display-freq-count)とすると、他のキーをタイプするまでの間だけ、同様な情報を一時的に表示する。

Command: edebug-display-freq-count

このコマンドは、カレント定義の各行の頻度数を表示する。

このコマンドは、コードの各行の下にコメント行として頻度数を挿入する。1回のundoコマンドで、すべての挿入をアンドゥできる。頻度数は式の前の‘(’、または式の後の‘)’、または変数の最後の文字の下に表示される。表示をシンプルにするために、同一行にたいして式の以前頻度数と頻度数が同じ場合は表示しない。

The character ‘=’ following the count for an expression says that the expression has returned the same value each time it was evaluated. In other words, it is not yet covered for coverage testing purposes.

ある定義にたいして頻度数とカバレッジデータを明確にするには、単にeval-defunで再インストルメントすればよい。

たとえば、ソースのbreakpointで(fac 5)を評価した後、edebug-test-coverageをtにセットすると、breakpointに達したときの頻度データは以下のようになります:

(defun fac (n)
  (if (= n 0) (edebug))
;#6           1      = =5
  (if (< 0 n)
;#5         =
      (* n (fac (1- n)))
;#    5               0
    1))
;#   0

コメント行は、facが6回呼び出されたことを表しています。最初のif命令は毎回同じ結果を5回リターンしています。同じ結果という意味では、2つ目のifの条件にも当てはまります。facの再帰呼び出しは、結局リターンしません。

18.2.14 コンテキスト外部

Edebugはデバッグ中のプログラムにたいして透過的であろうと努めますが、完全には達成されません。Edebugは、eや評価リストバッファーで式を評価するときも、一時的に外部のコンテキストをリストアして、透明化を試みます。このセクションではEdebugがリストアするコンテキストと、Edebugがいかにして完全に透過的になるのに失敗するかを正確に説明します。

18.2.14.1 停止するかどうかのチェック

Edebugにエンターするときは常に特定のデータの保存とリストアを行なう必要があり、それはトレース情報を作成するか、あるいはプログラムを停止するかを決定する前に行なう必要があります。

max-lisp-eval-depth (see section eval) and max-specpdl-size (see section ローカル変数) are both increased to reduce Edebug’s impact on the stack. You could, however, still run out of stack space when using Edebug. You can also enlarge the value of edebug-max-depth if Edebug reaches the limit of recursion depth instrumenting code that contains very large quoted lists.
キーボードマクロの実行状態は保存およびリストアされる。Edebugがアクティブの間、edebug-continue-kbd-macroがnilの場合は、executing-kbd-macroがnilにバインドされる。

18.2.14.2 Edebugの表示の更新

When Edebug needs to display something (e.g., in trace mode), it saves the current window configuration from outside Edebug (see section ウィンドウの構成). When you exit Edebug, it restores the previous window configuration.

Emacs redisplays only when it pauses. Usually, when you continue execution, the program re-enters Edebug at a breakpoint or after stepping, without pausing or reading input in between. In such cases, Emacs never gets a chance to redisplay the outside configuration. Consequently, what you see is the same window configuration as the last time Edebug was active, with no interruption.

何かを表示するためにEdebugにエントリーすることにより、(たとえこれらのうちのいくつかは、エラーやquitがシグナルされたときは、故意にリストアしないデータだとしても)以下のデータも保存およびリストアされます。

どれがカレントバッファーか、そしてカレントバッファー内のポイントとマークの位置が、保存およびリストアされる。
edebug-save-windowsが非nilの場合は、外部のウィンドウ構成が保存およびリストアされる(Edebugのオプションを参照)。
エラーやquitではウィンドウ構成はリストアされないが、save-excursionがアクティブな場合は、たとえエラーやquitのとき外部の選択されたウィンドウが再選択される。edebug-save-windowsの値がリストの場合は、それにリストされたウィンドウだけが保存およびリストアされる。

しかし、ソースコードバッファーのウィンドウの開始位置と水平スクロールはリストアされないので、表示はEdebug内で整合性が保たれたままとなる。
edebug-save-displayed-buffer-pointsが非nilの場合、表示されているそれぞれのバッファー内のポイント値は、保存およびリストアされる。
変数overlay-arrow-positionとoverlay-arrow-stringは保存およびリストアされるので、同じバッファー内の他の場所の再帰編集から、安全にEdebugを呼び出せる。
cursor-in-echo-areaはnilにローカルにバインドされるので、カーソルはそのウィンドウ内に現れる。

18.2.14.3 Edebugの再帰編集

Edebugにエンターしてユーザーのコマンドが実際に読み取られるとき、Edebugは以下の追加データを保存(そして後でリストア)します:

カレントマッチデータ。マッチデータを参照。
変数last-command、this-command、last-command-event、last-input-event、last-event-frame、last-nonmenu-event、track-mouse。Edebug内のコマンドは、Edebug外部のこれらの変数に影響をあたえない。
Edebug内でのコマンド実行は、this-command-keysによりリターンされるキーシーケンスを変更でき、Lispからそのキーシーケンスをリセットする方法はない。

Edebugはunread-command-eventsの値の保存およびリストアができない。この変数が重要な値をもつときにEdebugにエンターすると、デバッグ中のプログラムの実行に干渉する可能性がある。
Edebug内で実行された複雑なコマンドは、変数command-historyに追加される。これが稀に実行に影響を与える。
Edebug内では、再帰深さがEdebug外部の再帰深さより1つ深くなる。これは自動的に更新される評価リストウィンドウでは異なる。
standard-outputとstandard-inputはrecursive-editによりnilにバインドされるが、Edebugは評価の間それらを一時的にリストアする。
キーボードマクロ定義の状態は、保存およびリストアされる。Edebugがアクティブの間、defining-kbd-macroはedebug-continue-kbd-macroにバインドされる。

18.2.15 Edebugとマクロ

Edebugが正しくマクロを呼び出す式をインストルメントするには、いくつかの特定な配慮が必要になります。このサブセクションでは、その詳細を説明します。

18.2.15.1 マクロ呼び出しのインストルメント

EdebugがLispマクロを呼び出す式をインストルメントするときは、正しくインストルメントを行なうために、そのマクロに関して追加の情報が必要になります。これは、マクロ呼び出しのどの部分式(subexpression)が評価されるフォームなのか推測する方法がないからです。(評価はマクロのbodyで明示的に発生するかもしれないし、展開結果が評価されるとき、または任意のタイミングで行われるかもしれません。)

したがって、Edebugが処理するかもしれないすべてのマクロにたいして、そのマクロの呼び出しフォーマットを説明するための、Edebug仕様(Edebug specification)を定義しなければなりません。これを行なうには、マクロ定義にdebug宣言を追加します。以下はマクロ例for(マクロ引数の多重評価を参照)にたいする簡単な仕様の例です。

(defmacro for (var from init to final do &rest body)
  "Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
  (declare (debug (symbolp "from" form "to" form "do" &rest form)))
  ...)

このEdebug仕様は、マクロ呼び出しのどの部分が評価されるフォームなのかを示しています。単純なマクロにたいするEdebug仕様は、そのマクロ定義の正式な引数リストに非常に類似している場合がありますが、Edebug仕様はマクロ引数に比べより汎的です。declareフォームの詳細は、マクロの定義を参照してください。

Take care to ensure that the specifications are known to Edebug when you instrument code. If you are instrumenting a function which uses a macro defined in another file, you may first need to either evaluate the require forms in the file containing your function, or explicitly load the file containing the macro. If the definition of a macro is wrapped by eval-when-compile, you may need to evaluate it.

def-edebug-specによりマクロ定義から個々のマクロにたいしてEdebug仕様を定義することもできます。Lispで記述されたマクロ定義にたいしてはdebug宣言を追加するほうが好ましく、その方が便利でもありますが、def-edebug-specではCで実装されたスペシャルフォームにたいしてEdebug仕様を定義することが可能になります。

Macro: def-edebug-spec macro specification

マクロmacro呼び出しのどの式が評価される式かを指定する。specificationはEdebug仕様である。どちらの引数も評価されない。

引数macroは単なるマクロ名ではない、任意の実シンボルを指定できる。

以下はspecificationに指定できるシンボルと、引数を処理する方法のテーブルです。

t: すべての引数は評価のためにインストルメントされる。
0: 引数はインストルメントされない。
シンボル: そのシンボルは、かわりに使用されるEdebug仕様をもたなければならない。このインダイレクションは、他の種類の仕様が見つかるまで繰り返される。これにより、他のマクロの仕様を継承できる。
リスト: リストの要素はフォーム呼び出しの引数の型を記述する。仕様リストに指定できる要素については、以降のセクションを参照。

マクロがEdebug仕様をもたない場合は、debug宣言およびdef-edebug-spec呼び出しのどちらを通じても、変数edebug-eval-macro-argsが効果を発揮する。

User Option: edebug-eval-macro-args: これは、Edebugが明示的なEdebug仕様をもたないマクロ引数を扱う方法を制御する。nil(デフォルト)の場合、引数は評価のためにインストルメントされない。それ以外は、すべての引数がインストルメントされる。

18.2.15.2 仕様リスト

あるマクロ呼び出しにおいて、いくつかの引数は評価されるが、それ以外の引数は評価されないような場合には、Edebug仕様のために仕様リスト(specification list)が要求されます。仕様リスト内のいくつかの要素は1つ以上の引数にマッチしまづが、それ以外の要素は以降に続くすべての引数の処理を変更します。後者は仕様キーワード(specification keywords)と呼ばれ、(&optionalのように)‘&’で始まるシンボルです。

仕様リストは、それ自身がリストであるような引数にマッチする部分リスト(sublist)、またはグループ化に使用されるベクターを含むかもしれません。したがって部分式とグループは、仕様リストをレベル階層に細分化します。仕様キーワードは、部分式やグループを含むものの残りに適用されます。

仕様リストに選択肢や繰り返しが含まれる場合は、実際のマクロの呼び出しにたいしてマッチさせるためにバックトラックが要求されるかもしれません。詳細は、仕様でのバックトレースを参照してください。

Edebug仕様は、バランスのとれたカッコで括られた部分式へのマッチ、フォームの再帰処理、インダイレクト仕様を通じた再帰などの、正規表現によるマッチングと、コンテキストに依存しない文法構成を提供します。

以下は仕様リストに使用できる要素と、その意味についてのテーブルです(使用例は仕様の例を参照):

sexp

評価れない単一のLispオブジェクト。インストルメントされない。

form

A single evaluated expression, which is instrumented. If your macro wraps the expression with lambda before it is evaluated, use def-form instead. See def-form below.

place

汎変数(generalized variable)。ジェネリック変数を参照。

body

Short for &rest form. See &rest below. If your macro wraps its body of code with lambda before it is evaluated, use def-body instead. See def-body below.

function-form

関数フォーム。クォートされた関数シンボル、クォートされたラムダ式、または(関数シンボルかラムダ式に評価される)フォームのうちのどれか。これはラムダ式のbodyをいずれかの方法でインストルメントするため、functionよりもquoteでクォートされたラムダ式の引数にたいし有用。

lambda-expr

クォートされないラムダ式。

&optional

仕様リスト内の後続の要素はオプション。マッチしない要素が出現すると、Edebugはこのレベルのマッチングを停止する。

後続が非オプションの要素であるような数個の要素をオプションにするだけなら、[&optional specs…]を使用する。複数の要素すべてのマッチ、または非マッチを指定するには、&optional [specs…]を使用する。defunの例を参照。

&rest

仕様リスト内の後続のすべての要素は、0回以上繰り返される。しかし、最後の繰り返しでは、仕様リスト内のすべての要素にたいするマッチングの前に式が終了しても問題はない。

数個の要素を繰り返すには、[&rest specs…]を使用する。各繰り返しにおいいてすべてマッチしなければならない複数要素を指定するには、&rest [specs…]を使用する。

&or

仕様リスト内の後続の各要素は選択肢。選択肢の1つがマッチしなければならず、マッチしない場合&or仕様は失敗する。

&orに続く各リスト要素は、単一の選択肢。複数のリスト要素を単一の選択肢にグループ化するには、それらを[…]で括る。

&not

後続の各要素は、&orが使用されたときのように選択肢にマッチするが、要素がマッチした場合に失敗する。どれもマッチする要素がない場合は何もマッチされないが、&not仕様は成功する。

&define

Indicates that the specification is for a defining form. Edebug’s definition of a defining form is a form containing one or more code forms which are saved and executed later, after the execution of the defining form.

The defining form itself is not instrumented (that is, Edebug does not stop before and after the defining form), but forms inside it typically will be instrumented. The &define keyword should be the first element in a list specification.

nil

カレント引数レベルでマッチさせる引数が存在しない場合は成功し、それ以外は失敗する。部分リスト仕様とバッククォートの例を参照。

gate

引数はマッチされないがgateを通じたバックトラックは、このレベルの使用の残りをマッチングする間は無効にされる。これは主に、特定の構文エラーメッセージを一般的にするために使用される。詳細は仕様でのバックトレース、およびletの例も参照。

other-symbol

仕様リスト内のその他の要素は、述語(predicate)かインダイレクト仕様(indirect specification)である。

シンボルがEdebug仕様をもつ場合、インダイレクト仕様(indirect specification)はシンボル位置に使用されるリスト仕様か、引数を処理するための関数のどちらかである。この仕様はマクロにたいするdef-edebug-specのように定義される。defunの例を参照。

それ以外の場合、シンボルは述語(predicate)である。述語は引数とともに呼び出され、述語がnilをリターンした場合、その仕様は失敗して引数はインストルメントされない。

適切な述語としてはsymbolp、integerp、stringp、vectorp、atomが含まれる。

[elements…]

要素のベクターは、要素を単一のグループ仕様(group specification)にグループ化する。このグループ仕様は、ベクター自体に何も行わない。

"string"

引数はstringという名前のシンボルである。この仕様は、symbolの名前がstringであるクォートされたシンボル'symbolと等価だが、文字列形式のほうが好ましい。

(vector elements…)

引数は、要素が仕様内のelementsにマッチするベクターである。バッククォートの例を参照。

(elements…)

他のリストは部分リスト仕様(sublist specification)であり、引数は要素が仕様のelementsにマッチするリストでなければならない。

部分リスト仕様はドットリスト(dotted list)かもしれず、その場合対応するリスト引数はドットリストである。かわりに、ドットリスト仕様の最後のCDRが、(グループ化やインダイレクト仕様による)他の部分リスト仕様かもしれない(たとえば要素が非ドットリストにマッチする(spec . [(more specs…)])))。これはバッククォートの例のような再帰仕様に有用。このような再帰を終了させるには、上述のnil仕様も参照。

(specs . nil)のように記述された部分リスト仕様は(specs)、(specs . (sublist-elements…))は(specs sublist-elements…)と等価であることに注意。

以下は&defineの後だけに出現する追加仕様のリストです。defunの例を参照してください。

name

引数(シンボル)は定義フォームの名前。

定義フォームは名前フィールドをもつ必要はなく、複数の名前フィールドをもつかもしれない。

:name

この構成は引数に実際のマッチは行わない。:nameの後の要素はシンボルであり、その定義の追加の名前要素として使用される。定義名に一意で静的な要素を加えるために、これを使用できる。複数回使用されるかもしれない。

arg

引数(シンボル)は定義フォームの引数の名前である。しかし、lambda-listキーワード(‘&’で始まるシンボル)は許されない。

lambda-list

これはラムダリスト(ラムダ式の引数リスト)にマッチする。

def-body

引数は定義内のコードのbodyである。これは上述のbodyと似ているが、定義のbodyはその定義に関連する情報を照会する別のEdebug呼び出しでインストルメントされていなければならない。定義内のより高位レベルのフォームリストには、def-bodyを使用する。

def-form

引数は、定義内のもっとも高位レベルの単一フォームである。これはdef-bodyと似ているが、フォームリストではなく単一フォームのマッチに使用される。特別なケースとして、def-formはフォームが実行されるときトレース情報を出力しないことも意味する。interactiveの例を参照。

18.2.15.3 仕様でのバックトレース

あるポイント位置で仕様がマッチに失敗しても、構文エラーがシグナルされるとは限りません。そのかわりバックトラック(backtracking)が開始されます。バックトラックは、すべての選択肢をマッチングするまで行なわれます。最終的に引数リストのすべての要素は仕様内の要素のいずれかとマッチしなければならず、仕様内の必須要素は引数のいずれかとマッチしなければなりません。

構文エラーが検出されてもその時点では報告されず、より高位レベルの選択肢のマッチングが終わった後、実際のエラー箇所から離れたポイント位置でエラーが報告されるかもしれません。しかしエラー発生時にバックトラックが無効なら、エラーは即座に報告されるでしょう。ある状況においては、バックトラックも自動的に再有効化されることに注意してください。&optional、&rest、&orにより新たな選択肢が設定されたとき、または部分リスト、グループ、インダイレクト仕様が開始されたときは、バックトラックが自動的に有効になります。バックトラックを有効、または無効にした場合の影響は、現在処理中のレベルの残り要素と、低位レベルに限定されます。

何らかのフォーム仕様(すなわちform、body、def-form、def-body)をマッチングする間、バックトラックは無効になっています。これらの仕様は任意のフォームにマッチするので、何らかのエラーが発生するとしたらそれは高位レベルではなく、そのフォーム自体の内部でなければなりません。

バックトラックはクォートされたシンボルや文字列仕様とのマッチに成功した後にも無効になります。なぜなら通常これは構成が認識されたことを示すからです。しかし、同じシンボルで始まる一連の選択肢構成がある場合は、たとえば["foo" &or [first case] [second case] ...]のように、通常は選択肢の外部にそのシンボルをファクタリングすることにより、この制約に対処できます。

ほとんどのニーズは、バックトラックを自動的に無効にする、これら2つの方法で満足させることができますが、gate仕様を使用して明示的にバックトラックを無効にするほうが便利なときもあります。これは、高位に適用可能な選択肢が存在しないことが分かっている場合に有用です。let仕様の例を参照してください。

18.2.15.4 仕様の例

以下で提供する例から学ぶことにより、Edebug仕様の理解が容易になるかもしれません。

スペシャルフォームletは、バインディングとbodyのシーケンスをもちます。各バインディングはそシンボル、またはシンボルとオプションの部分リストです。以下の仕様では、部分リストを見つけたらバックトラックを抑止するために、部分リスト内のgateがあることに注目してください。

(def-edebug-spec let
  ((&rest
    &or symbolp (gate symbolp &optional form))
   body))

Edebugはdefunおよび関連する引数リスト、interactive仕様にたいして以下の仕様を使用します。式の引数はその関数bodyの外部で実際に評価されるので、interactiveフォームは特別に処理する必要があります。(defmacroにたいする仕様はdefunにたいする仕様と非常に似ていますが、declare命令文が許されます。)

(def-edebug-spec defun
  (&define name lambda-list
           [&optional stringp]   ; ドキュメント文字列が与えられた場合はマッチする。
           [&optional ("interactive" interactive)]
           def-body))

(def-edebug-spec lambda-list
  (([&rest arg]
    [&optional ["&optional" arg &rest arg]]
    &optional ["&rest" arg]
    )))

(def-edebug-spec interactive
  (&optional &or stringp def-form))    ; Notice: def-form

以下のバッククォートにたいする仕様は、ドットリストにマッチさせる方法と、nilを使用して再帰を終了させる方法を説明するための例です。また、ベクターのコンポーネントをマッチさせる方法も示しています。(Edebugにより定義される実際の仕様は少し異なり、ドットリストについては失敗するかもしれない非常に深い再帰を引き起こすためサポートしていません。)

(def-edebug-spec \` (backquote-form))   ; Alias just for clarity.

(def-edebug-spec backquote-form
  (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
       (backquote-form . [&or nil backquote-form])
       (vector &rest backquote-form)
       sexp))

18.2.16 Edebugのオプション

以下のオプションは、Edebugの動作に影響を与えます:

User Option: edebug-setup-hook: Edebugが使用される前に呼び出される関数。この関数は毎回新たな値をセットする。Edebugこれらの関数を一度呼び出したら、その後edebug-setup-hooknilにリセットする。使用するパッケージに関係するEdebug仕様をロードするために使用ｄきるが、それはEdebugを使用するときだけである。Edebugのためのインストルメントを参照。

User Option: edebug-all-defs

これが非nilの場合はdefunやdefmacroのような定義フォームの普通に評価すると、Edebug用にインストルメントされる。これはeval-defun、eval-region、eval-buffer、and eval-current-bufferに適用される。

このオプションの切り替えには、コマンドM-x edebug-all-defsを使用する。Edebugのためのインストルメントを参照。

User Option: edebug-all-forms

これが非nilの場合eval-defun、eval-region、eval-buffer、eval-current-bufferは、たとえフォームが何も定義していなくても、すべてのフォームをインストルメントする。これはロードとミニバッファー内の評価には適用されない。

このオプションの切り替えには、コマンドM-x edebug-all-formsを使用する。Edebugのためのインストルメントを参照。

User Option: edebug-eval-macro-args: When this is non-nil, all macro arguments will be instrumented in the generated code. For any macro, an edebug-form-spec overrides this option. So to specify exceptions for macros that have some arguments evaluated and some not, use def-edebug-spec to specify an edebug-form-spec.

User Option: edebug-save-windows

これが非nilの場合、Edebugはウィンドウ構成の保存とリストアを行なう。これにはある程度時間がかかるので、ウィンドウ構成に何が起こってもプログラムに関係しない場合は、この変数をnilにセットしたほうがよい。

値がリストの場合は、リストされたウィンドウだけが保存およびリストアされる。

Edebug内では、この変数をインタラクティブに変更するためにWコマンドを使用できる。Edebugの表示の更新を参照。

User Option: edebug-save-displayed-buffer-points

これが非nilの場合、Edebugは表示されているすべてのバッファー内のポイントを保存およびリストアする。

選択されていないウィンドウ内に表示されているバッファーのポイントを変更するコードをデバッグしている場合は、他のバッファーのポイントを保存およびリストアする必要がある。その後にEdebugまたはユーザーがそのウィンドウを選択した場合は、そのバッファー内のポイントは、そのウィンドウのポイント値に移動される。

すべてのバッファー内のポイントの保存とリストアは、それぞれのウィンドウを2回選択する必要があり高価な処理のため、必要なときだけ有効にする。Edebugの表示の更新を参照。

User Option: edebug-initial-mode

この変数が非nilの場合、Edebugが最初にアクティブになったときの、Edebugの最初の実行モードを指定する。指定できる値はstep、next、go、Go-nonstop、trace、Trace-fast、continue、Continue-fast。

The default value is step. This variable can be set interactively with C-x C-a C-m (edebug-set-initial-mode). See section Edebugの実行モード.

User Option: edebug-trace

これが非nilの場合が、各関数のエントリーとexitをトレースする。トレース出力は、関数のエントリーとexitを行ごとに、再帰レベルにしたがって*edebug-trace*という名前のバッファーに表示される。

トレースバッファーのedebug-tracingも参照のこと。

User Option: edebug-test-coverage: 非nilの場合、Edebugはデバッグされるすべての式のカバレッジをテストする。カバレッジテストを参照。

User Option: edebug-continue-kbd-macro: 非nilの場合は、Edebug外で実行されている任意のキーボードマクロの定義または実行を継続する。これはデバッグされないので、慎重に使用すること。Edebugの実行モードを参照。

User Option: edebug-print-length: If non-nil, the default value of print-length for printing results in Edebug. See section 出力に影響する変数.

User Option: edebug-print-level: If non-nil, the default value of print-level for printing results in Edebug. See section 出力に影響する変数.

User Option: edebug-print-circle: If non-nil, the default value of print-circle for printing results in Edebug. See section 出力に影響する変数.

User Option: edebug-unwrap-results

非nilの場合、Edebugは式の結果を表示するときに、その式自体のインストルメント結果の削除を試みる。マクロをデバッグするときは、式の結果自体がインストルメントされた式になるということに関連する。実際的な例ではないが、サンプル例の関数facがインストルメントされたとき、そのフォームのマクロを考えてみるとよい。

(defmacro test () "Edebug example."
  (if (symbol-function 'fac)
      …))

If you instrument the test macro and step through it, then by default the result of the symbol-function call has numerous edebug-after and edebug-before forms, which can make it difficult to see the actual result. If edebug-unwrap-results is non-nil, Edebug tries to remove these forms from the result.

User Option: edebug-on-error: debug-on-errorの以前がnilの場合、Edebugはdebug-on-errorをこの値にバインドする。エラーのトラップを参照。

User Option: edebug-on-quit: debug-on-quitの以前の値がnilの場合、Edebugはdebug-on-quitにこの値をバインドする。エラーのトラップを参照。

Edebugがアクティブな間にedebug-on-errorまたはedebug-on-quitの値を変更した場合は、次回に新たなコマンドを通じてEdebugが呼び出されるまで、これらの値は使用されない。

User Option: edebug-global-break-condition: 非nilの場合、値はすべてのステップポイントでテストされる式である。式の結果がnilの場合は、breakする。エラーは無視される。グローバルなブレーク条件を参照。

User Option: edebug-sit-for-seconds: Number of seconds to pause when a breakpoint is reached and the execution mode is trace or continue. See section Edebugの実行モード.

User Option: edebug-sit-on-break: Whether or not to pause for edebug-sit-for-seconds on reaching a breakpoint. Set to nil to prevent the pause, non-nil to allow it.

18.3 無効なLisp構文のデバッグ

The Lisp reader reports invalid syntax, but cannot say where the real problem is. For example, the error ‘End of file during parsing’ in evaluating an expression indicates an excess of open parentheses (or square brackets). The reader detects this imbalance at the end of the file, but it cannot figure out where the close parenthesis should have been. Likewise, ‘Invalid read syntax: ")"’ indicates an excess close parenthesis or missing open parenthesis, but does not say where the missing parenthesis belongs. How, then, to find what to change?

問題が単なるカッコの不一致でない場合の便利なテクニックは、各defunの先頭でC-M-eとタイプして、そのdefunの最後と思われる箇所に移動するか確認する方法です。もし移動しなければ、問題はそのdefunの内部にあります。

マッチしないカッコがLispにおいてもっとも一般的な構文エラーなので、これらのケースにたいしてさらにアドバイスすることができます。(Show Parenモードを有効にしてコードにポイントを移動するだけで、カッコの不一致を探しやすくなるでしょう。)

18.3.1 過剰な開カッコ

カッコがマッチしないdefunを探すのが、最初のステップです。過剰な開カッコが存在する場合は、ファイルの終端に移動してC-u C-M-uとタイプします。これにより、カッコがマッチしない最初のdefunの先頭に移動するでしょう。

何が間違っているのか正確に判断するのが次のステップです。これを確実に行なうには、そのプログラムを詳しく調べる以外に方法はありませんが、カッコがあるべき箇所を探すのに、既存のインデントが手掛かりになることが多々あります。C-M-qで再インデントして何が移動されるか確認するのが、この手掛かりを使用するもっとも簡単な方法です。しかし、行うのはちょっと待ってください! まず続きを読んでからにしましょう。

これを行なう前に、defunに十分な閉カッコがあるか確認します。十分な閉カッコがない場合、C-M-qがエラーとなるか、そのdefunからファイル終端までの残りすべてが再インデントされます。その場合はdefunの最後に移動して、そこに閉カッコを挿入します。そのdefunのカッコの釣り合いがとれるまでは、defunの最後に移動するのにC-M-eは使用できません(失敗するでしょう)。

これでdefunの先頭に移動してC-M-qとタイプすることができます。通常は、一定のポイントからその関数の最後までのすべての行が、右へとシフトされるでしょう。これはおそらくそのポイント付近で閉カッコが欠落しているか、不要な開カッコがあります。(しかし、これを真実と仮定せず、コードを詳しく調べてください。) 不一致箇所が見つけたら、元のインデントはおそらく意図されたカッコに適しているはずなので、C-_でC-M-qをアンドゥしてください。

問題をfixできたと思った後に、再度C-M-qを使用します。実際に元のインデントが意図したカッコのネストに適合していて、足りないカッコを追加していたら、C-M-qは何も変更しないはずです。

18.3.2 過剰な閉カッコ

過剰な閉カッコへの対処は、まずファイルの先頭に移動してから、カッコのマッチしないdefunを探すためにC-u -1 C-M-uをタイプします。

それから、そのdefunの先頭でC-M-fをタイプして、実際にマッチする閉カッコを探します。これにより、そのdefunの終端より幾分手前の箇所に移動するでしょう。その付近に間違った閉カッコが見つかるでしょう。

そのポイントに問題が見つからない場合には、そのdefunの先頭でC-M-qをタイプするのが次のステップです。ある行範囲はおそらく左へシフトするでしょう。その場合、欠落している開カッコまたは間違った閉カッコは、おそらくそれらの行の1行目の近くにあるでしょう。 (しかし、これを真実と仮定せず、コードを詳しく調べてください。)不一致箇所が見つけたら、元のインデントはおそらく意図されたカッコに適しているはずなので、C-_でC-M-qをアンドゥしてください。

18.4 カバレッジテスト

testcoverライブラリーをロードして、コマンドM-x testcover-start RET file RETでコードをインストルメントすることにより、Lispコードのファイルにたいしてカバレッジテストを行なうことができます。コードを1回以上呼び出すことにより、テストが行なわれます。コマンドM-x testcover-mark-allを使用すれば、カバレッジが不十分な箇所が色付きでハイライト表示されます。コマンドM-x testcover-next-markは、次のハイライトされた箇所へポイントを前方に移動します。

通常、赤くハイライトされた箇所はそのフォームが完全に評価されたことが一度もないことを示し、茶色でハイライトされた箇所は常に同じ値に評価された(その結果にたいして少ししかテストされていない)ことを意味します。しかし、errorのように完全に評価するのが不可能なフォームにたいしては、赤いハイライトはスキップされます。(setq x 14)のように、常に同じ値に評価されることが期待されるフォームにたいしては、茶色のハイライトスキップされます。

難しいケースでは、テストカバレッジツールにアドバイスを与えるために、コードにdo-nothingマクロを追加することができます。

Macro: 1value form: formを評価してその値をリターンするが、テストカバレッジにたいしてformが常に同じ値だという情報を与える。

Macro: noreturn form: formを評価し、formが決してリターンしないという情報をカバレッジテストに与える。もしリターンした場合は、run-timeエラーとなる。

Edebugにもカバレッジテスト機能があります(カバレッジテストを参照)。これらの機能は部分的に重複しており、組み合わせることで明確になるでしょう。

18.5 プロファイリング

If your program is working correctly, but not fast enough, and you want to make it run more quickly or efficiently, the first thing to do is profile your code so that you know where it spends most of the execution time. If you find that one particular function is responsible for a significant portion of the execution time, you can start looking for ways to optimize that piece.

Emacs has built-in support for this. To begin profiling, type M-x profiler-start. You can choose to profile by processor usage, memory usage, or both. Then run the code you’d like to speed up. After that, type M-x profiler-report to display a summary buffer for each resource (cpu and memory) that you chose to profile. The names of the report buffers include the times at which the reports were generated, so you can generate another report later on without erasing previous results. When you have finished profiling, type M-x profiler-stop (there is a small overhead associated with profiling, so we don’t recommend leaving it active except when you are actually running the code you want to examine).

The profiler report buffer shows, on each line, a function that was called, followed by how much resources (cpu or memory) it used in absolute and percentage terms since profiling started. If a given line has a ‘+’ symbol at the left-hand side, you can expand that line by typing RET, in order to see the function(s) called by the higher-level function. Use a prefix argument (C-u RET) to see the whole call tree below a function. Pressing RET again will collapse back to the original state.

Press j or mouse-2 to jump to the definition of a function at point. Press d to view a function’s documentation. You can save a profile to a file using C-x C-w. You can compare two profiles using =.

The elp library offers an alternative approach, which is useful when you know in advance which Lisp function(s) you want to profile. Using that library, you begin by setting elp-function-list to the list of function symbols—those are the functions you want to profile. Then type M-x elp-instrument-list RET nil RET to arrange for profiling those functions. After running the code you want to profile, invoke M-x elp-results to display the current results. See the file elp.el for more detailed instructions. This approach is limited to profiling functions written in Lisp, it cannot profile Emacs primitives.

You can measure the time it takes to evaluate individual Emacs Lisp forms using the benchmark library. See the macros benchmark-run and benchmark-run-compiled in benchmark.el. You can also use the benchmark command for timing forms interactively.

configureのオプションに--enable-profilingを使用してビルドすることにより、EmacsをCコードのレベルでプロファイルすることができます。こうしてビルドされたEmacsは、Emacsをexitするときにgprofユーティリティを使用して検証できるファイルgmon.outを生成します。この機能は主にEmacsのデバッグに有用です。このEmacsは、実行状態から上述のM-x profiler-…コマンドによりLispレベルで実際にストップします。

19 Lispオブジェクトの読み取りとプリント

プリント(print)および読み取り(read)は、Lispオブジェクトからテキスト形式への変換、またはその逆の変換を行なう操作です。これらはLispのデータ型で説明したプリント表現(printed representation)と入力構文(read syntax)を使用します。

このチャプターでは、読み取りおよびプリントのためのLisp関数について説明します。このチャプターではさらにストリーム(stream)についても説明します。ストリームとは、(読み取りにおいては)テキストがどこから取得されるか、(プリントにおいては)テキストをどこに出力するかを指定します。

19.1 読み取りとプリントの概念		ストリーム、読み取り、プリントの概観。
19.2 入力ストリーム		入力ストリームとして使用できる、さまざまなデータ型。
19.3 入力関数		テキストからLispオブジェクトを読み取る関数。
19.4 出力ストリーム		出力ストリームとして使用できる、さまざまなデータ型。
19.5 出力関数		テキストとしてLispオブジェクトをプリントする関数。
19.6 出力に影響する変数		プリント関数が何を行うか制御する変数。

19.1 読み取りとプリントの概念

Lispオブジェクトの読み取りとは、テキスト形式のLisp式をパース(parse: 構文解析)して、対応するLispオブジェクトを生成することを意味します。これは、LLispプログラムがLispコードファイルからLispに取得される方法でもあります。わたしたちは、そのテキストをそのオブジェクトの入力構文(read syntax)と呼んでいます。たとえばテキスト‘(a . 5)’は、CARがaでCDRが数字の5であるようなコンスセルにたいする入力構文です。

Lispオブジェクトのプリントとは、あるオブジェクトをそのオブジェクトのプリント表現(printed representation) (プリント表現と読み取り構文を参照)に変換することにより、そのオブジェクトを表すテキストを生成することを意味します。上述のコンスセルをプリントすると、テキスト‘(a . 5)’が生成されます。

読み取りとプリントは、概ね逆の処理といえます。あるテキスト断片を読み取った結果生成されたオブジェクトをプリントすると、多くの場合は同じテキストが生成され、あるオブジェクトをプリントした結果のテキストを読み取ると、通常は同じようなオブジェクトが生成されます。たとえばシンボルfooをプリントするとテキスト‘foo’が生成され、そのテキストを読み取るとシンボルfooがリターンされます。要素がaとbのリストをプリントするとテキスト‘(a b)’が生成され、そのテキストを読み取ると、(同じリストではないが)要素がaとbのリストが生成されます。

しかし、これら2つの処理は互いにまったく逆の処理というわけではありません。３つの例外があります:

プリントは読み取ることが不可能なテキストを生成できる。たとえば、バッファー、フレーム、サブプロセス、マーカーは‘#’で始まるテキストとしてプリントされる。このテキストの読み取りを試行すると、エラーとなる。これらのデータ型を読み取る方法は存在しない。
1つのオブジェクトが、複数のテキスト的な表現をもつことができる。たとえば‘1’と‘01’は同じ整数を表し、‘(a b)’と‘(a . (b))’は同じリストを表す。読み取りは複数の候補を受容するかもしれないが、プリントはそのうちのただ1つを選択しなければならない。
あるオブジェクトの読み取りシーケンスの中間の特定ポイントに、読み取り結果に影響を与えないコメントを置くことができる。

19.2 入力ストリーム

テキストを読み取るLisp関数の大部分は、引数として入力ストリーム(input stream)をとります。入力ストリームは、読み取られるテキストの文字をどこから、どのように取得するかを指定します。以下は可能な入力ストリーム型です:

buffer

入力文字はbufferのポイントの後の文字から直接読み取られる。文字の読み取りとともに、ポイントが進む。

marker

入力文字はmarkerのあるバッファーの、マーカーの後の文字から直接読み取られる。文字の読み取りとともに、マーカーが進む。ストリームがマーカーのときは、バッファー内のポイント値に影響はない。

string

入力文字はstringの最初の文字から必要な文字数分が取得される。

function

入力文字はfunctionから生成され、その関数は2種類の呼び出しをサポートしなければならない:

引数なしで呼び出されたときは、次の文字をリターンする。
When it is called with one argument (always a character), function should save the argument and arrange to return it on the next call. This is called unreading the character; it happens when the Lisp reader reads one character too many and wants to put it back where it came from. In this case, it makes no difference what value function returns.

t

tは、その入力がミニバッファーから読み取られるストリームであることを意味する。実際にはミニバッファーが1回呼び出されて、ユーザーから与えられたテキストが、その後に入力ストリームとして使用される文字列となる。Emacsがbatchモードで実行されている場合は、ミニバッファーのかわりに標準入力が使用される。たとえば、

(message "%s" (read t))

このような場合は標準入力からLisp式が読み取られて、結果は標準出力にプリントされるだろう。

nil

入力ストリームとしてnilが与えられた場合は、かわりにstandard-inputの値が使用されることを意味する。この値はデフォルトの入力ストリーム(default input stream)であり、非nilの入力ストリームでなければならない。

symbol

入力ストリームとしてのシンボルは、(もしあれば)そのシンボルの関数定義と等価である。

以下の例では、バッファーストリームから読み込み、読み取りの前後におけるポイント位置を示しています:

---------- Buffer: foo ----------
This∗ is the contents of foo.
---------- Buffer: foo ----------

(read (get-buffer "foo"))
     ⇒ is

(read (get-buffer "foo"))
     ⇒ the

---------- Buffer: foo ----------
This is the∗ contents of foo.
---------- Buffer: foo ----------

最初の読み取りではスペースがスキップされていることに注意してください。読み取りにおいては、意味のあるテキストに先行する、任意のサイズの空白文字がスキップされます。

以下は、マーカーストリームからの読み取りの例で、最初は表示されているバッファーの先頭にマーカーが配します。読み取られた値はシンボルThisです。


---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------

(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
     ⇒ #<marker at 1 in foo>

(read m)
     ⇒ This

m
     ⇒ #<marker at 5 in foo>   ;; 最初のスペースの前。

以下では、文字列のコンテンツから読み取っています:

(read "(When in) the course")
     ⇒ (When in)

以下はミニバッファーから読み取る例です。プロンプトは、‘Lisp expression: ’です。(このプロンプトはストリームtから読み取る際は常に使用されます。) ユーザーの入力はプロンプトの後に表示されます。

(read t)
     ⇒ 23
---------- Buffer: Minibuffer ----------
Lisp expression: 23 RET
---------- Buffer: Minibuffer ----------

最後は、useless-streamという名前の関数ストリームから読み取る例です。ストリームを使用する前に、変数useless-listを文字のリストに初期化しています。その後は、リスト内の次の文字を取得するため、または文字をリストの先頭に追加することにより読み戻すために、関数useless-streamを呼び出します。

(setq useless-list (append "XY()" nil))
     ⇒ (88 89 40 41)

(defun useless-stream (&optional unread)
  (if unread
      (setq useless-list (cons unread useless-list))
    (prog1 (car useless-list)
           (setq useless-list (cdr useless-list)))))
     ⇒ useless-stream

このストリームを使って、以下のように読み取ります:

(read 'useless-stream)
     ⇒ XY

useless-list
     ⇒ (40 41)

開カッコと閉カッコがリスト内に残ることに注意してください。Lispリーダーは開カッコに出会うと、それを入力の終わりと判断して、読み戻します。次にこのポイント位置からこのストリームを読み取ると、‘()’が読み取られてnilがリターンされます。

19.3 入力関数

このセクションでは、読み取りに関係のあるLisp関数と変数について説明します。

以下の関数で、streamは入力ストリーム(前のセクションを参照)を意味します。streamがnil、または省略された場合のデフォルト値はstandard-inputです。

読み取りにおいて終端されていないリスト、ベクター、文字列に遭遇した場合は、end-of-fileがシグナルされます。

Function: read &optional stream: この関数はstreamからテキスト表現されたLisp式を1つ読み取り、Lispオブジェクトとしてリターンする。これは基本的なLisp入力関数である。

Function: read-from-string string &optional start end

この関数はstring内のテキストから、最初のテキスト表現されたLisp式を読み取る。リターン値はCARがその式で、CDRが次に読み取られるその文字列内の残りの文字(読み取られていない最初の文字)の位置を与える整数であるようなコンスセルである。

startが与えられた場合は、文字列内のインデックスstart(最初の文字はインデックス0)から読み取りが開始される。endを指定した場合は、残りの文字列が存在しないかのごとく、そのインデックスの直前で読み取りがストップされる。

たとえば:

(read-from-string "(setq x 55) (setq y 5)")
     ⇒ ((setq x 55) . 11)

(read-from-string "\"A short string\"")
     ⇒ ("A short string" . 16)

;; Read starting at the first character.
(read-from-string "(list 112)" 0)
     ⇒ ((list 112) . 10)

;; Read starting at the second character.
(read-from-string "(list 112)" 1)
     ⇒ (list . 5)

;; Read starting at the seventh character,
;;   and stopping at the ninth.
(read-from-string "(list 112)" 6 8)
     ⇒ (11 . 8)

Variable: standard-input: この変数はデフォルト入力ストリーム(引数streamがnilのときreadが使用するストリーム)を保持する。デフォルトはtで、これはミニバッファーを使用することを意味する。

Variable: read-circle: 非nilの場合、この変数は循環構造(circular structure)および共有構造(shared structures)の読み取りを有効にする。循環オブジェクトの読み取り構文を参照。デフォルト値はt。

When reading or writing from the standard input/output streams of the Emacs process in batch mode, it is sometimes required to make sure any arbitrary binary data will be read/written verbatim, and/or that no translation of newlines to or from CR-LF pairs is performed. This issue does not exist on POSIX hosts, only on MS-Windows and MS-DOS. The following function allows you to control the I/O mode of any standard stream of the Emacs process.

Function: set-binary-mode stream mode: Switch stream into binary or text I/O mode. If mode is non-nil, switch to binary mode, otherwise switch to text mode. The value of stream can be one of stdin, stdout, or stderr. This function flushes any pending output data of stream as a side effect, and returns the previous value of I/O mode for stream. On POSIX hosts, it always returns a non-nil value and does nothing except flushing pending output.

19.4 出力ストリーム

出力ストリームは、プリントにより生成された文字に何を行うかを指定します。ほとんどのプリント関数は、オプション引数として出力ストリームを受け入れます。以下は利用できる出力ストリーム型です:

buffer: 出力文字は、bufferのポイント位置に挿入される。文字が挿入された分、ポイントが進む。
marker: 出力文字は、markerのあるバッファーのマーカー位置に挿入される。文字が挿入された分、マーカー位置が進む。ストリームがマーカーのときは、そのバッファー内のポイント位置にプリントは影響せず、この種のプリントでポイントは移動しない(マーカー位置がポイント位置、またはポイント位置より前の場合は除外される。通常はテキストの周囲にポイントが進む)。
function: 出力文字は、文字を格納する役目をもつfunctionに渡される。この関数は１つの文字を引数に、出力される文字の回数呼び出され、その文字を格納したい場所に格納する役目をもつ。
t: 出力文字はエコーエリアに表示される。
nil: 出力ストリームにnilが指定された場合は、かわりにstandard-outputの値が使用されることを意味する。この値はデフォルトの出力ストリーム(default output stream)であり、非nilでなければならない。
symbol: 出力ストリームとしてのシンボルは、(もしあれば)そのシンボルの関数定義と等価である。

有効な出力ストリームの多くは、入力ストリームとしても有効です。したがって入力ストリームと出力ストリームの違いは、Lispオブジェクトの型ではなく、どのようにLispオブジェクトを使うかという点です。

以下はバッファーを出力ストリームとして使用する例です。ポイントは最初は‘the’の中の‘h’の直前にあります。そして最後も、同じ‘h’の直前に配されます。

---------- Buffer: foo ----------
This is t∗he contents of foo.
---------- Buffer: foo ----------


(print "This is the output" (get-buffer "foo"))
     ⇒ "This is the output"

---------- Buffer: foo ----------
This is t
"This is the output"
∗he contents of foo.
---------- Buffer: foo ----------

次はマーカーを出力ストリームとして使用する例です。マーカーは最初、バッファーfoo内の単語‘the’の中の‘t’と‘h’の間にあります。最後には、挿入されたテキストによりマーカーが進み、同じ‘h’の前に留まります。通常の方法で見られるようなポイント位置への影響がないことに注意してください。

---------- Buffer: foo ----------
This is the ∗output
---------- Buffer: foo ----------

(setq m (copy-marker 10))
     ⇒ #<marker at 10 in foo>

(print "More output for foo." m)
     ⇒ "More output for foo."

---------- Buffer: foo ----------
This is t
"More output for foo."
he ∗output
---------- Buffer: foo ----------

m
     ⇒ #<marker at 34 in foo>

以下はエコーエリアに出力を表示する例です:

(print "Echo Area output" t)
     ⇒ "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------

最後は関数を出力ストリームとして使用する例です。関数eat-outputは与えられたそれぞれの文字をlast-outputの先頭にconsします(コンスセルおよびリストの構築を参照)。最後には、リストには出力されたすべての文字が逆順で含まれます。

(setq last-output nil)
     ⇒ nil

(defun eat-output (c)
  (setq last-output (cons c last-output)))
     ⇒ eat-output

(print "This is the output" #'eat-output)
     ⇒ "This is the output"

last-output
     ⇒ (10 34 116 117 112 116 117 111 32 101 104
    116 32 115 105 32 115 105 104 84 34 10)

このリストを逆転すれば、正しい順序で出力することができます:

(concat (nreverse last-output))
     ⇒ "
\"This is the output\"
"

concatを呼び出してリストを文字列に変換すれば、内容をより明解に確認できます。

Function: external-debugging-output character

This function can be useful as an output stream when debugging. It writes character to the standard error stream.

For example

(print "This is the output" #'external-debugging-output)
-| This is the output
⇒ "This is the output"

19.5 出力関数

このセクションでは、オブジェクトをオブジェクトのプリント表現に変換してLispオブジェクトをプリントするLisp関数を説明します。

Emacsプリント関数には、正しく読み取れるように必要なとき出力にクォート文字を追加するものがあります。使用されるクォート文字は‘"’と‘\’です。これらは文字列をシンボルと区別するとともに、文字列およびシンボル内の区切り文字が読み取り時に区切り文字として扱われることを防ぎます。完全な詳細はプリント表現と読み取り構文を参照してください。クォートするかしないかは、プリント関数の選択により指定できます。

そのテキストがLispに読み戻す場合、同様にLispプログラマーにLispオブジェクトを明解に説明するのが目的の場合は、曖昧さを避けるためにクォート文字をプリントするべきです。しかし、プログラマー以外の人間にたいして出力の見栄えを良くするのが目的なら、通常はクォートなしでプリントしたほうがよいでしょう。

Lispオブジェクトは自己参照ができます。通常の方法で自己参照オブジェクトをプリントするにはテキストが無限に必要で、その試みにより無限再帰が発生する恐れがあります。Emacsはそのような再帰を検知して、すでにプリントされたオブジェクトを再帰的にプリントするかわりに、‘#level’をプリントします。たとえば以下は、カレントのプリント処理において、レベル0のオブジェクトを再帰的に参照することを示しています:

(setq foo (list nil))
     ⇒ (nil)
(setcar foo foo)
     ⇒ (#0)

In the functions below, stream stands for an output stream. (See the previous section for a description of output streams. Also See external-debugging-output, a useful stream value for debugging.) If stream is nil or omitted, it defaults to the value of standard-output.

Function: print object &optional stream

print関数は、プリントを行うための便利な方法である。この関数はobjectの前後に改行を付与して、objectのプリント表現をstreamにプリントする。クォート文字が使用される。printはobjectをリターンする。たとえば:

(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     -|
     -| The\ cat\ in
     -|
     -| "the hat"
     -|
     -| " came back"
     ⇒ " came back"

Function: prin1 object &optional stream

この関数はobjectのプリント表現をstreamに出力する。この関数はprintのように出力を分割するための改行をプリントしないが、printのようにクォート文字を使用する。objectをリターンする。

(progn (prin1 'The\ cat\ in)
       (prin1 "the hat")
       (prin1 " came back"))
     -| The\ cat\ in"the hat"" came back"
     ⇒ " came back"

Function: princ object &optional stream

この関数はobjectのプリント表現をstreamに出力する。objectをリターンする。

この関数はreadではなく人間が読める出力を生成することを意図しているので、クォート文字を挿入せず、文字列のコンテンツの前後にダブルクォート文字を配さない。呼び出しの間に間隔を何も出力しない。

(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     -| The cat in the "hat"
     ⇒ " in the \"hat\""

Function: terpri &optional stream ensure: This function outputs a newline to stream. The name stands for “terminate print”. If ensure is non-nil no newline is printed if stream is already at the beginning of a line. Note in this case stream can not be a function and an error is signaled if it is. This function returns t if a newline is printed.

Function: write-char character &optional stream: この関数はcharacterをstreamに出力する。characterをリターンする。

Function: prin1-to-string object &optional noescape

この関数は、同じ引数でprin1がプリントするテキストを含む文字列をリターンする。

(prin1-to-string 'foo)
     ⇒ "foo"

(prin1-to-string (mark-marker))
     ⇒ "#<marker at 2773 in strings.texi>"

noescapeが非nilの場合は、出力中のクォート文字の使用を抑制する。(この引数は、Emacsバージョン19以降でサポートされた。)

(prin1-to-string "foo")
     ⇒ "\"foo\""

(prin1-to-string "foo" t)
     ⇒ "foo"

Lispオブジェクトのプリント表現を文字列として取得する別の手段については、文字列のフォーマットのformatを参照のこと。

Macro: with-output-to-string body…

このマクロは出力を文字列に送るようstandard-outputをセットアップして、フォームbodyを実行する。その文字列がリターンされる。

たとえばカレントバッファー名が‘foo’の場合、

(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))

は"The buffer is foo"をリターンする。

Function: pp object &optional stream: This function outputs object to stream, just like prin1, but does it in a prettier way. That is, it’ll indent and fill the object to make it more readable for humans.

If you need to use binary I/O in batch mode, e.g., use the functions described in this section to write out arbitrary binary data or avoid conversion of newlines on non-POSIX hosts, see set-binary-mode.

19.6 出力に影響する変数

Variable: standard-output: この変数の値はデフォルト出力ストリーム(stream引数がnilのときプリント関数が使用するストリーム)である。デフォルトはtで、エコーエリアに表示することを意味する。

Variable: print-quoted: これが非nilの場合は、省略されたリーダー構文(たとえば(quote foo)を'foo、(function foo)を#'fooのように)を使用してクォートされたフォームをプリントすることを意味する。

Variable: print-escape-newlines

この変数が非nilの場合、文字列内の改行は‘\n’、改ページは‘\f’でプリントされる。これらの文字は、通常は実際の改行および改ページとしてプリントされる。

この変数はクォートつきのプリントを行うプリント関数prin1およびprintに影響を与える。princに影響はない。以下はprin1を使用した場合の例である:

(prin1 "a\nb")
     -| "a
     -| b"
     ⇒ "a
b"

(let ((print-escape-newlines t))
  (prin1 "a\nb"))
     -| "a\nb"
     ⇒ "a
b"

2つ目の式では、prin1を呼び出す間はprint-escape-newlinesのローカルバインドが効果をもつが、結果をプリントするときには効果がない。

Variable: print-escape-control-characters: If this variable is non-nil, control characters in strings are printed as backslash sequences by the print functions prin1 and print that print with quoting. If this variable and print-escape-newlines are both non-nil, the latter takes precedences for newlines and formfeeds.

Variable: print-escape-nonascii

この変数が非nilの場合、クォートつきでプリントするプリント関数prin1およびprintは、文字列内のユニバイトの非ASCII文字を無条件でバックスラッシュシーケンスとしてプリントする。

これらの関数は、出力ストリームがマルチバイトバッファー、あるいはマーカーがマルチバイトバッファーをポイントするときは、この変数の値に関わらずユニバイト非ASCII文字にたいしてバックスラッシュシーケンスを使用する。

Variable: print-escape-multibyte

この変数が非nilの場合、クォートつきでプリントするプリント関数prin1およびprintは、文字列内のマルチバイトの非ASCII文字を無条件でバックスラッシュシーケンスとしてプリントする。

これらの関数は、出力ストリームがユニバイトバッファー、あるいはマーカーがユニバイトバッファーをポイントするときは、この変数の値に関わらずマルチバイト非ASCII文字にたいしてバックスラッシュシーケンスを使用する。

Variable: print-length

この変数の値は任意のリスト、ベクター、ブールベクターをプリントする際の最大要素数である。プリントされるオブジェクトがこれより多くの要素をもつ場合は、省略記号(“...”)で省略される。

値がnil(デフォルト)の場合は、無制限である。

(setq print-length 2)
     ⇒ 2

(print '(1 2 3 4 5))
     -| (1 2 ...)
     ⇒ (1 2 ...)

Variable: print-level: この変数の値はプリント時の丸カッコ(parentheses: “()”)と角カッコ(brackets: “[]"’)のネスト最大深さである。この制限を超える任意のリストまたはベクターは省略記号(“...”)で省略される。値nil(デフォルト)は無制限を意味する。

User Option: eval-expression-print-length
User Option: eval-expression-print-level: これらはeval-expressionにより使用されるprint-lengthおよびprint-levelの値であり、したがって間接的に多くのインタラクティブな評価コマンドにより使用される(Evaluating Emacs-Lisp Expressions in The GNU Emacs Manualを参照)。

以下の変数は循環構造および共有構造の検出と報告に使用されます:

Variable: print-circle: 非nilの場合、この変数はプリント時の循環構造と共有構造の検出を有効にする。循環オブジェクトの読み取り構文を参照のこと。

Variable: print-gensym: 非nilの場合、この変数はプリント時のインターンされていないシンボル(シンボルの作成とinternを参照)の検出を有効にする。これが有効な場合、インターンされていないシンボルはプレフィックス‘#:’とともにプリントされる。このプレフィックスは、Lispリーダーにたいしてインターンされていないシンボルを生成するよう告げる。

Variable: print-continuous-numbering: 非nilの場合は、複数のプリント呼び出しを通じて通番が振られることを意味する。これは‘#n=’ラベルおよび‘#m#’参照にたいしてプリントされる数字に影響する。この変数をsetqでセットしてはならない。letを使用して一時的にtにバインドするべきである。これを行う場合は、print-number-tableもnilにバインドするべきである。

Variable: print-number-table: この変数はprint-circle機能を実装するために、プリント処理で内部的に使用されるベクターを保持する。print-continuous-numberingをバインドするときにこの変数をnilにバインドする以外は、この変数を使用するべきではない。

Variable: float-output-format

この変数は浮動小数点数をプリントする方法を指定する。デフォルトはnilで、これは情報を失わずにその数値を表せるもっとも短い出力を使用することを意味する。

出力フォーマットをより精密に制御するために、この変数に文字列をセットできる。この文字列にはCのsprintf関数で使用される‘%’指定子をセットする。この変数で使用することのできる制限についての詳細は、この変数のドキュメント文字列を参照のこと。

20 ミニバッファー

ミニバッファー(minibuffer)とは、単一の数プレフィックス引数より複雑な引数を読み取るためにEmacsコマンドが使用する、特別なバッファーのことです。これらの引数にはファイル名、バッファー名、(M-xでの)コマンド名が含まれます。ミニバッファーはフレームの最下行、エコーエリア(エコーエリアを参照)と同じ場所に表示されますが、引数を読み取るときだけ使用されます。

20.1 ミニバッファーの概念		ミニバッファーに関する基本的な情報。
20.2 ミニバッファーでのテキスト文字列の読み取り		そのままのテキスト文字列を読み取る方法。
20.3 ミニバッファーでのLispオブジェクトの読み取り		Lispオブジェクトや式を読み取る方法。
20.4 ミニバッファーのヒストリー		ユーザーが再利用できるように以前のミニバッファー入力は記録される。
20.5 入力の初期値		ミニバッファーにたいして初期内容を指定する。
20.6 補完		補完の呼び出しとカスタマイズ方法。
20.7 Yes-or-Noによる問い合わせ		問いにたいし単純な答えを求める。
20.8 複数のY-or-Nの問い合わせ		一連の似たような問いに答える。
20.9 パスワードの読み取り		端末からパスワードを読み取る。
20.10 ミニバッファーのコマンド		ミニバッファー内でキーバインドとして使用されるコマンド。
20.11 ミニバッファーのウィンドウ		特殊なミニバッファーウィンドウを処理する。
20.12 ミニバッファーのコンテンツ		どのようなコマンドがミニバッファーのテキストにアクセスするか。
20.13 再帰的なミニバッファー		ミニバッファーへの再帰的なエントリーが許容されるかどうか。
20.14 ミニバッファー、その他の事項		カスタマイズ用のさまざまなフックや変数。

20.1 ミニバッファーの概念

ほとんどの点において、ミニバッファーは普通のEmacsバッファーです。編集コマンドのようなバッファーにたいするほとんどの操作は、ミニバッファーでも機能します。しかし、バッファーを管理する操作の多くは、ミニバッファーに適用できません。ミニバッファーは常に‘ *Minibuf-number*’という形式の名前をもち、変更することはできません。ミニバッファーはミニバッファー用の特殊なウィンドウだけに表示されます。これらのウィンドウは常にフレーム最下に表示されます。(フレームにミニバッファーウィンドウがないときや、ミニバッファーウィンドウだけをもつ特殊なフレームもあります。)ミニバッファーとフレームを参照してください。

ミニバッファー内のテキストは常にプロンプト文字列(prompt string)で始まります。これはミニバッファーを使用しているプログラムが、ユーザーにたいしてどのような種類の入力が求められているか告げるために指定するテキストです。このテキストは意図せずに変更してしまわないように、読み取り専用としてマークされます。このテキストはbeginning-of-line、forward-word、forward-sentence、forward-paragraphを含む特定の移動用関数が、プロンプトと実際のテキストの境界でストップするように、フィールド(フィールドの定義と使用を参照)としてもマークされています。

The minibuffer’s window is normally a single line; it grows automatically if the contents require more space. Whilst the minibuffer is active, you can explicitly resize its window temporarily with the window sizing commands; the window reverts to its normal size when the minibuffer is exited. When the minibuffer is not active, you can resize its window permanently by using the window sizing commands in the frame’s other window, or dragging the mode line with the mouse. (Due to details of the current implementation, for this to work resize-mini-windows must be nil.) If the frame contains just a minibuffer window, you can change its size by changing the frame’s size.

ミニバッファーの使用により入力イベントが読み取られ、this-commandやlast-commandのような変数の値が変更されます(コマンドループからの情報を参照)。プログラムにそれらを変更させたくない場合は、ミニバッファーを使用するコードの前後でそれらをバインドするべきです。

Under some circumstances, a command can use a minibuffer even if there is an active minibuffer; such a minibuffer is called a recursive minibuffer. The first minibuffer is named ‘ *Minibuf-1*’. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won’t show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently entered) is the active minibuffer. We usually call this the minibuffer. You can permit or forbid recursive minibuffers by setting the variable enable-recursive-minibuffers, or by putting properties of that name on command symbols (See section 再帰的なミニバッファー.)

他のバッファーと同様、ミニバッファーは特別なキーバインドを指定するためにローカルキーマップ(キーマップを参照)を使用します。ミニバッファーを呼び出す関数も、処理を行うためにローカルマップをセットアップします。補完なしのミニバッファーローカルマップについては、ミニバッファーでのテキスト文字列の読み取りを参照してください。補完つきのミニバッファーローカルマップについては、補完を行うミニバッファーコマンドを参照してください。

ミニバッファーが非アクティブのときのメジャーモードはminibuffer-inactive-modeで、キーマップはminibuffer-inactive-mode-mapです。これらは、実際にはミニバッファーが別フレームにある場合だけ、便利です。ミニバッファーとフレームを参照してください。

When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started. This supports only basic input: none of the special minibuffer features (history, completion, etc.) are available in batch mode.

20.2 ミニバッファーでのテキスト文字列の読み取り

ミニバッファー入力にたいする基本的なプリミティブはread-from-minibufferで、これは文字列とLispオブジェクトの両方からテキスト表現されたフォームを読み取ることができます。関数read-regexpは、特別な種類の文字列である正規表現式(正規表現を参照)の読み取りに使用されます。コマンドや変数、ファイル名などの読み取りに特化した関数もあります(補完を参照)。

ほとんどの場合では、Lisp関数の途中でミニバッファー入力関数を呼び出すべきではありません。かわりにinteractive指定されたコマンドの引数読み取りの一部として、すべてのミニバッファー入力を行います。コマンドの定義を参照してください。

Function: read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method

この関数は、ミニバッファーから入力を取得するもっとも一般的な手段である。デフォルトでは、任意のテキストを受け入れて、それを文字列としてリターンする。しかし、readが非nilの場合は、テキストをLispオブジェクトに変換するためにreadを使用する(入力関数を参照)。

この関数が最初に行うのは、ミニバッファーをアクティブにして、プロンプトにprompt(文字列でなければならない)を用いてミニバッファーを表示することである。その後に、ユーザーはミニバッファーでテキストを編集できる。

ミニバッファーをexitするためにユーザーがコマンドをタイプするとき、read-from-minibufferはミニバッファー内のテキストからリターン値を構築する。通常はそのテキストを含む文字列がリターンされる。しかし、readが非nilの場合、read-from-minibufferはテキストを読み込んで結果を未評価のLispオブジェクトでリターンする。(読み取りについての詳細は、See section 入力関数を参照のこと。)

引数defaultは、ヒストリーコマンドを通じて利用できるデフォルト値を指定する。値には文字列、文字列リスト、またはnilを指定する。文字列または文字列リストは、ユーザーがM-nで利用可能な“未来のヒストリー(future history)”になります。

readが非nilの場合は、ユーザーの入力が空のときのreadの入力としても、defaultが使用される。defaultが文字列リストの!は、最初の文字列が入力として使用される。defaultがnilの場合、空の入力はend-of-fileエラーとなる。しかし通常(readがnil)の場合には、ユーザーの入力が空のときread-from-minibufferはdefaultを無視して、空文字列""をリターンする。この点において、この関数はこのチャプターの他のどのミニバッファー入力関数とも異なる。

keymapが非nilの場合、そのキーマップはミニバッファー内で使用されるローカルキーマップとなる。keymapが省略、またはnilの場合は、minibuffer-local-mapの値がキーマップとして使用される。キーマップの指定は、補完のようなさまざまなアプリケーションにたいしてミニバッファーをカスタマイズする、もっとも重要な方法である。

引数historyは、入力の保存やミニバッファー内で使用されるヒストリーコマンドが使用するヒストリーリスト変数を指定する。デフォルトはminibuffer-historyである。同様に、オプションでヒストリーリスト内の開始位置を指定できる。ミニバッファーのヒストリーを参照のこと。

変数minibuffer-allow-text-propertiesが非nilの場合には、リターンされる文字列にはミニバッファーでのすべてのテキストプロパティが含まれる。それ以外では、値がリターンされるときすべてのテキストプロパティが取り除かれる。

The text properties in minibuffer-prompt-properties are applied to the prompt. By default, this property list defines a face to use for the prompt. This face, if present, is applied to the end of the face list and merged before display.

If the user wants to completely control the look of the prompt, the most convenient way to do that is to specify the default face at the end of all face lists. For instance:

(read-from-minibuffer
 (concat
  (propertize "Bold" 'face '(bold default))
  (propertize " and normal: " 'face '(default))))

引数inherit-input-methodが非nilの場合には、ミニバッファーにエンターする前にカレントだったバッファーが何であれ、カレントのインプットメソッド(入力メソッドを参照)、およびenable-multibyte-charactersのセッティング(テキストの表現方法を参照)が継承される。

ほとんどの場合、initialの使用は推奨されない。非nil値の使用は、historyにたいするコンスセル指定と組み合わせる場合のみ推奨する。入力の初期値を参照のこと。

Function: read-string prompt &optional initial history default inherit-input-method

この関数はミニバッファーから文字列を読み取り、それをリターンする。引数prompt、initial、history、inherit-input-methodはread-from-minibufferで使用する場合と同様。使用されるキーマップはminibuffer-local-mapである。

オプション引数defaultはread-from-minibufferの場合と同様に使用されるが、ユーザーの入力が空の場合にリターンするデフォルト値も指定する。read-from-minibufferの場合と同様、値は文字列、文字列リスト、またはnil(空文字列と等価)である。defaultが文字列のときは、その文字列がデフォルト値になる。文字列リストのときは、最初の文字列がデフォルト値になる。(これらの文字列はすべて“未来のミニバッファーヒストリー(future minibuffer history)”としてユーザーが利用可能)。

この関数はread-from-minibufferを呼び出すことにより機能する。

(read-string prompt initial history default inherit)
≡
(let ((value
       (read-from-minibuffer prompt initial nil nil
                             history default inherit)))
  (if (and (equal value "") default)
      (if (consp default) (car default) default)
    value))

Function: read-regexp prompt &optional defaults history

この関数はミニバッファーから文字列として正規表現を読み取り、それをリターンする。ミニバッファーのプロンプト文字列promptが‘:’(とその後にオプションの空白文字)で終端されていない場合、この関数はデフォルトのリターン値(空文字列でない場合。以下参照)の前に‘:’を付加する。

オプション引数defaultsは、入力が空の場合にリターンするデフォルト値を制御する。値は文字列、nil(空文字列と等価)、文字列リスト、シンボルのうちのどれか。

defaultsがシンボルの場合、read-regexpは変数read-regexp-defaults-function(以下参照)の値を調べて非nilのときは、defaultsよりそちらを優先的に使用する。この場合、値は以下のいずれか:

- regexp-history-last。これは適切なミニバッファーヒストリーリスト(以下参照)の最初の要素を使用することを意味する。
- 引数なしの関数。リターン値(nil、文字列、文字列リストのいずれか)がdefaultsの値となる。

これで、read-regexpがdefaultsを処理した結果はリストに確定する(値がnilまたは文字列の場合は1要素のリストに変換する)。このリストにたいし、read-regexpは、以下のような入力として有用な候補をいくつか追加する:

- ポイント位置の単語またはシンボル。
- インクリメンタル検索で最後に使用されたregexp。
- インクリメンタル検索で最後に使用された文字列。
- 問い合わせつき置換コマンドで最後に使用された文字列またはパターン。

The function now has a list of regular expressions that it passes to read-from-minibuffer to obtain the user’s input. The first element of the list is the default result in case of empty input. All elements of the list are available to the user as the “future minibuffer history” list (see future list in The GNU Emacs Manual).

オプション引数historyが非nilの場合、それは使用するミニバッファーヒストリーリストを指定するシンボルである(ミニバッファーのヒストリーを参照)。これが省略、またはnilの場合、ヒストリーリストのデフォルトはregexp-historyとなる。

User Option: read-regexp-defaults-function

関数read-regexpは、デフォルトの正規表現リストを決定するために、この変数の値を使用するかもしれない。非nilの場合、この変数は以下のいずれかである:

- シンボルregexp-history-last。
- nil、文字列、文字列リストのいずれかをリターンする引数なしの関数。

これらの変数の使い方についての詳細は、上述のread-regexpを参照のこと。

Variable: minibuffer-allow-text-properties: この変数がnilの場合、read-from-minibufferおよびread-stringはミニバッファー入力をリターンする前に、すべてのテキストプロパティを取り除く。しかしread-no-blanks-input(以下参照)、同様に補完つきでミニバッファー入力を行うread-minibufferおよびそれに関連する関数(Reading Lisp Objects With the Minibufferを参照)は、この変数の値に関わらず、無条件でテキストプロパティを破棄する。

Variable: minibuffer-local-map

これはミニバッファーからの読み取りにたいするデフォルトローカルキーマップである。デフォルトでは以下のバインディングをもつ:

C-j: exit-minibuffer
RET: exit-minibuffer
C-g: abort-recursive-edit
M-n
DOWN: next-history-element
M-p
UP: previous-history-element
M-s: next-matching-history-element
M-r: previous-matching-history-element

Function: read-no-blanks-input prompt &optional initial inherit-input-method

この関数はミニバッファーから文字列を読み取るが、入力の一部として空白文字を認めず、かわりに空白文字は入力を終端させる。引数prompt、initial、inherit-input-methodはread-from-minibufferで使用するときと同様。

これは関数read-from-minibufferの簡略化されたインターフェイスであり、キーマップminibuffer-local-ns-mapの値をkeymap引数として、read-from-minibuffer関数に渡す。キーマップminibuffer-local-ns-mapはC-qをリバインドしないので、クォートすることにより文字列内にスペースを挿入することが可能である。

minibuffer-allow-text-propertiesの値に関わらず、この関数はテキストプロパティを破棄する。

(read-no-blanks-input prompt initial)
≡
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer prompt initial minibuffer-local-ns-map))

Variable: minibuffer-local-ns-map

このビルトイン変数は関数read-no-blanks-input内でミニバッファーローカルキーマップとして使用されるキーマップである。デフォルトでは、minibuffer-local-mapのバインディングに加えて、以下のバインディングが有効になる:

SPC: exit-minibuffer
TAB: exit-minibuffer
?: self-insert-and-exit

20.3 ミニバッファーでのLispオブジェクトの読み取り

このセクションでは、ミニバッファーでLispオブジェクトを読み取る関数を説明します。

Function: read-minibuffer prompt &optional initial

この関数はミニバッファーを使用してLispオブジェクトをよみ、それを評価せずにリターンする。引数promptとinitialは、read-from-minibufferのときと同様に使用する。

これはread-from-minibuffer関数にたいする簡略化されたインターフェイスである。

(read-minibuffer prompt initial)
≡
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer prompt initial nil t))

以下の例では、初期入力として文字列"(testing)"を与えている:

(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))

;; 以下はミニバッファーでの表示::

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)∗
---------- Buffer: Minibuffer ----------

ユーザーはRETをタイプして初期入力をデフォルトとして利用したり、入力を編集することができる。

Function: eval-minibuffer prompt &optional initial

この関数はミニバッファーを使用してLisp式を読み取り、それを評価して結果をリターンする。引数promptとinitialの使い方は、read-from-minibufferと同様。

この関数は、read-minibufferの呼び出し結果を単に評価する:

(eval-minibuffer prompt initial)
≡
(eval (read-minibuffer prompt initial))

Function: edit-and-eval-command prompt form

この関数はミニバッファーでLisp式を読み取り、それを評価して結果をリターンする。このコマンドとeval-minibufferの違いは、このコマンドでは初期値としてのformはオプションではなく、テキストの文字列ではないプリント表現に変換されたLispオブジェクトとして扱われることである。これはprin1でプリントされるので、文字列の場合はテキスト初期値内にダブルクォート文字(‘"’)が含まれる。出力関数を参照のこと。

以下の例では、すでに有効なフォームであるようなテキスト初期値として式をユーザーに提案している:

(edit-and-eval-command "Please edit: " '(forward-word 1))

;; 前の式を評価した後に、
;;   ミニバッファーに以下が表示される。:

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)∗
---------- Buffer: Minibuffer ----------

すぐにRET をタイプするとミニバッファーをexitして式を評価するので、1単語分ポイントは前進する。

20.4 ミニバッファーのヒストリー

ミニバッファーヒストリーリスト(minibuffer history list)は以前のミニバッファー入力を記録するので、それらを手軽に再利用できます。ミニバッファーヒストリーリストは、(以前に入力された)文字列のリストで、もっとも最近の文字列が先頭になります。

多数のミニバッファーが個別に存在し、異なる入力の種類に使用されます。それぞれのミニバッファー使用にたいして正しいヒストリーリストを指定するのは、Lispプログラマーの役目です。

ミニバッファーヒストリーリストは、read-from-minibufferおよびcompleting-readのオプション引数historyに指定します。以下が利用できる値です:

variable

ヒストリーリストとしてvariable(シンボル)を使用する。

(variable . startpos)

ヒストリーリストとしてvariable(シンボル)を使用し、ヒストリー位置の初期値をstartpos(負の整数)とみなす。

startposに0を指定するのは、単にシンボルvariableだけを指定するのと等価である。previous-history-elementはミニバッファー内のヒストリーリストの最新の要素を表示するだろう。正のstartposを指定した場合、ミニバッファーヒストリー関数は(elt variable(1- startpos))がミニバッファー内でカレントで表示されているヒストリー要素であるかのように振る舞う。

一貫性を保つため、ミニバッファー入力関数のinitial引数(入力の初期値を参照)使用して、ミニバッファーの初期内容となるヒストリー要素も指定すべきである。

historyを指定しない場合は、デフォルトのヒストリーリストminibuffer-historyが使用されます。他の標準的なヒストリーリストについては、以下を参照してください。最初に使用する前にnilに初期化するだけで、独自のヒストリーリストを作成することもできます。

read-from-minibufferとcompleting-readは、どちらも新たな要素を自動的にヒストリーリストに追加して、ユーザーがそのリストのアイテムを再使用するためのコマンドを提供します。ヒストリーリストを使用するためにプログラムが行う必要があるのは、リストの初期化と、使用するときに入力関数にリストの名前を渡すだけです。しかし、ミニバッファー入力関数がリストを使用していないときに、手動でリストを変更しても問題はありません。

新たな要素をヒストリーリストに追加するEmacs関数は、リストが長くなりすぎたときに古い要素の削除も行うことができます。変数history-lengthは、ほとんどのヒストリーリストの最大長を指定する変数です。特定のヒストリーリストにたいして異なる最大長を指定するには、そのヒストリーリストシンボルのhistory-lengthプロパティにその最大長をセットします。変数history-delete-duplicatesには、ヒストリー内の重複を削除するかどうかを指定します。

Function: add-to-history history-var newelt &optional maxelt keep-all

この関数はneweltが空文字列でなければ、それを新たな要素として変数history-varに格納されたヒストリーリストに追加して、更新されたヒストリーリストをリターンする。これはmaxeltまたはhistory-lengthがが非nilの場合は、リストの長さをその変数の値に制限する(以下参照)。maxeltに指定できる値の意味は、history-lengthの値と同様。

add-to-historyは通常、history-delete-duplicatesが非nilならば、ヒストリーリスト内の重複メンバーを削除する。しかし、keep-allが非nilの場合、それは重複を削除しないことを意味し、たとえneweltが空でもリストに追加する。

Variable: history-add-new-input: この変数の値がnilの場合、ミニバッファーから読み取りを行う標準的な関数は、ヒストリーリストに新たな要素を追加しない。これにより、Lispプログラムがadd-to-historyを使用して明示的に入力ヒストリーを管理することになる。デフォルト値はt。

User Option: history-length: この変数の値は、最大長を独自に指定しないすべてのヒストリーリストの最大長を指定する。値がtの場合は、最大長がない(古い要素を削除しない)ことを意味する。ヒストリーリスト変数のシンボルのhistory-lengthプロパティが非nilの場合には、その特定のヒストリーリストにたいする最大長として、そのプロパティ値がこの変数をオーバーライドする。

User Option: history-delete-duplicates: この変数の値がtの場合、それは新たなヒストリー要素の追加時に、以前からある等しい要素が削除されることを意味する。

以下は、標準的なミニバッファーヒストリーリスト変数です:

Variable: minibuffer-history: ミニバッファーヒストリー入力にたいするデフォルトのヒストリーリスト。

Variable: query-replace-history: query-replaceの引数(および他のコマンドの同様の引数)にたいするヒストリーリスト。

Variable: file-name-history: ファイル名引数にたいするヒストリーリスト。

Variable: buffer-name-history: バッファー名引数にたいするヒストリーリスト。

Variable: regexp-history: 正規表現引数にたいするヒストリーリスト。

Variable: extended-command-history: 拡張コマンド名引数にたいするヒストリーリスト。

Variable: shell-command-history: シェルコマンド引数にたいするヒストリーリスト。

Variable: read-expression-history: 評価されるためのLisp式引数にたいするヒストリーリスト。

Variable: face-name-history: フェイス引数にたいするヒストリーリスト。

20.5 入力の初期値

ミニバッファー入力にたいする関数のいくつかには、initialと呼ばれる引数があります。これは通常のように空の状態で開始されるのではなく、特定のテキストとともにミニバッファーが開始されることを指定しますが、ほとんどの場合において推奨されない機能です。

initialが文字列の場合、ミニバッファーはその文字列のテキストを含む状態で開始され、ユーザーがそのテキストの編集を開始するとき、ポイントはテキストの終端にあります。ユーザーがミニバッファーをexitするために単にRETをタイプした場合には、この入力文字列の初期値をリターン値だと判断します。

initialにたいして非nil値の使用には反対します。なぜなら初期入力は強要的なインターフェイスだからです。ユーザーにたいして有用なデフォルト入力を提案するためには、ヒストリーリストやデフォルト値の提供のほうが、より便利です。

しかしinitial引数にたいして文字列を指定すべき状況が1つだけあります。それは、history引数にコンスセルを指定したときです。ミニバッファーのヒストリーを参照してください。

initialは(string . position)という形式をとることもできます。これはstringをミニバッファーに挿入するが、その文字列のテキスト中のpositionにポイントを配するという意味です。

歴史的な経緯により、positionは異なる関数において実装が統一されていません。completing-readではpositionの値は0基準です。つまり、値0は文字列の先頭で、1は最初の文字の次、...を意味します。しかしread-minibuffer、およびこの引数をサポートする補完を行わない他のミニバッファー入力関数では、1は文字列の先頭、2は最初の文字の次、...を意味します。

initialの値としてのコンスセルの使用は、推奨されません。

20.6 補完

補完(complete, ompletion)は省略された形式から始まる名前の残りを充填する機能です。補完はユーザー入力と有効な名前リストを比較して、ユーザーが何をタイプしたかで名前をどの程度一意に判定できるか判断することにより機能します。たとえばC-x b(switch-to-buffer)とタイプしてから、スイッチしたいバッファー名の最初の数文字をタイプして、その後にTAB(minibuffer-complete)をタイプすると、Emacsはその名前を可能な限り展開します。

標準的なEmacsコマンドはシンボル、ファイル、バッファー、プロセスの名前にたいして補完を提案します。このセクションの関数により、他の種類の名前にたいしても補完を実装できます。

try-completion関数は補完にたいする基本的なプリミティブです。これは初期文字列にたいして文字列セットをマッチして、最長と判定された補完をリターンします。

関数completing-readは、補完にたいする高レベルなインターフェイスを提供します。completing-readの呼び出しにより、有効な名前リストの判定方法が指定されます。その後にこの関数は補完にたいして有用ないくつかのコマンドにキーバインドするローカルキーマップとともに、ミニバッファーをアクティブ化します。その他の関数は、特定の種類の名前を補完つきで読み取る、簡便なインターフェイスを提供します。

20.6.1 基本的な補完関数		文字列を補完する低レベル関数。
20.6.2 補完とミニバッファー		補完つきでミニバッファーを呼び出す。
20.6.3 補完を行うミニバッファーコマンド
20.6.4 高レベルの補完関数		特別なケースに有用な補完(バッファー名や変数名などの読み取り)。
20.6.5 ファイル名の読み取り		ファイル名やシェルコマンドの読み取りに補完を使用する。
20.6.6 補完変数		補完の挙動を制御する変数。
20.6.7 プログラムされた補完		独自の補完関数を記述する。
20.6.8 通常バッファーでの補完		通常バッファー内でのテキスト補完。

20.6.1 基本的な補完関数

以下の補完関数は、その関数自身ではミニバッファーでなにも行いません。ここでは、ミニバッファーを使用する高レベルの補完機能と並べて、これらの関数について説明します。

Function: try-completion string collection &optional predicate

この関数はcollection内のstringに利用可能なすべての補完の、共通する最長部分文字列をリターンする。

collectionは補完テーブル(completion table)と呼ばれる。値は文字列リスト、コンスセル、obarray、ハッシュテーブル、または補完関数でなければならない。

try-completionは補完テーブルにより指定された許容できる補完それぞれにたいして、stringと比較を行う。許容できる補完マッチが存在しない場合は、nilをリターンする。マッチする補完が1つだけで、それが完全一致ならばtをリターンする。それ以外は、すべてのマッチ可能な補完に共通する最長の初期シーケンス(longest initial sequence)をリターンする。

collectionがリストの場合、許容できる補完(permissible completions)はそのリストの要素により指定される。リストの要素は文字列、またはCARが文字列または(symbol-nameにより文字列に変換される)シンボルであるようなコンスセルである。リストに他の型の要素が含まれる場合は無視される。

collectionがobarray(シンボルの作成とinternを参照)の場合、そのobarray内のすべてのシンボル名が許容できる補完セットを形成する。

If collection is a hash table, then the keys that are strings or symbols are the possible completions. Other keys are ignored.

collectionとして関数を使用することもできる。この場合、この関数だけが補完を処理する役目を担う。つまりtry-completionは、この関数が何をリターンしようとも、それをリターンする。この関数はstring、predicate、nilの3つの引数で呼び出される(3つ目の引数は同じ関数をall-completionsでも使用して、どちらの場合でも適切なことを行うためである)。プログラムされた補完を参照のこと。

引数predicateが非nilの場合、collectionがハッシュテーブルなら1引数、それ以外は2引数の関数でなければならない。これは利用可能なマッチのテストに使用され、マッチはpredicateが非nilをリターンしたときだけ受け入れられる。predicateに与えられる引数は文字列、alistのコンスセル(CARが文字列)、またはobarrayのシンボル(シンボル名ではない)のうちのどれか。collectionがハッシュテーブルの場合、predicateは文字列キー(string key)と関連値(associated value)の2引数で呼び出される。

加えて使いやすいように、補完はcompletion-regexp-list内のすべての正規表現にもマッチしなければならない。(collectionが関数の場合は、その関数自身がcompletion-regexp-listを処理する必要がある。)

以下の例の1つ目では、文字列‘foo’がalistのうち3つのCARとマッチされている。すべてのマッチは文字‘fooba’で始まるので、それが結果となる。2つ目の例では、可能なマッチは1つだけで、しかも完全一致なのでリターン値はtになる。

(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     ⇒ "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     ⇒ t

以下の例では、文字‘forw’で始まるシンボルが多数あり、それらはすべて単語‘forward’で始まる。ほとんどのシンボルはその後に‘-’が続くが、すべてではないので‘forward’までしか補完できない。

(try-completion "forw" obarray)
     ⇒ "forward"

最後に、以下の例では述語testに渡される利用可能なマッチは3つのうち2つだけである(文字列‘foobaz’は短すぎる)。これらは両方とも文字列‘foobar’で始まる。

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test

(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ "foobar"

Function: all-completions string collection &optional predicate

この関数は、stringの利用可能な補完すべてのリストをリターンする。この関数の引数はtry-completionの引数と同じであり、try-completionが行うのと同じ方法でcompletion-regexp-listを使用する。

collectionか関数の場合はstring、predicate、tの3つの引数で呼び出される。この場合、その関数がリターンするのが何であれ、all-completionsはそれをリターンする。プログラムされた補完を参照のこと。

以下の例は、try-completionの例の関数testを使用している。

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ ("foobar1" "foobar2")

Function: test-completion string collection &optional predicate

この関数は、stringがcollectionおよびpredicateで指定された有効な補完候補の場合は、nilをリターンする。引数はtry-completionの引数と同じ。たとえば、collectionが文字列リストの場合は、stringがリスト内に存在し、かつpredicateを満足すればtrueとなる。

この関数はtry-completionが行うのと同じ方法で、completion-regexp-listを使用する。

predicateが非nilで、collectionが同じ文字列を複数含む場合には、completion-ignore-caseにしたがってcompare-stringsで判定して、それらすべてをリターンするか、もしくは何もリターンしない。それ以外では、test-completionのリターン値は基本的に予測不可能である。

collectionが関数の場合はstring、predicate、lambdaの3つの引数で呼び出される。それが何をリターンするにせよ、test-completionはそれをリターンする。

Function: completion-boundaries string collection predicate suffix

この関数はポイントの前のテキストがstring、ポイントの後がsuffixと仮定して、collectionが扱うフィールドの境界(boundary)をリターンする。

補完は通常、文字列(string)全体に作用するので、すべての普通のコレクション(collection)にたいして、この関数は常に(0 . (length suffix))をリターンするだろう。しかしファイルにたいする補完などのより複雑な補完は、1回に1フィールド行われる。たとえば、たとえ"/usr/share/doc"が存在しても、"/usr/sh"の補完に"/usr/share/"は含まれるが、"/usr/share/doc"は含まれないだろう。また、"/usr/sh"にたいするall-completionsに"/usr/share/"は含まれず、"share/"だけが含まれるだろう。stringが"/usr/sh"、suffixが"e/doc"の場合、completion-boundariesは(5 . 1)をリターンするだろう。これは、collectionが"/usr/"の後ろにあり"/doc"の前にある領域に関する補完情報だけをリターンするであろうことを告げている。

If you store a completion alist in a variable, you should mark the variable as risky by giving it a non-nil risky-local-variable property. See section ファイルローカル変数.

Variable: completion-ignore-case: この変数の値が非nilの場合、補完での大文字小文字の違いは意味をもたない。read-file-nameでは、この変数はread-file-name-completion-ignore-case(ファイル名の読み取りを参照)にオーバーライドされる。read-bufferでは、この変数はread-buffer-completion-ignore-case(高レベルの補完関数を参照)にオーバーライドされる。

Variable: completion-regexp-list: これは正規表現のリストである。補完関数はこのリスト内のすべての正規表現にマッチした場合のみ許容できる補完と判断する。case-fold-search(検索と大文字小文字を参照)ではcompletion-ignore-caseの値にバインドされる。

Macro: lazy-completion-table var fun

この変数は変数varを補完のためのcollectionとしてlazy(lazy: 力のない、だらけさせる、のろのろした、怠惰な、不精な、眠気を誘う)な方法で初期化する。ここでlazyとは、collection内の実際のコンテンツを必要になるまで計算しないという意味。このマクロはvarに格納する値の生成に使用する。varを使用して最初に補完を行ったとき、真の値が実際に計算される。これは引数なしでfunを呼び出すことにより行われる。funがリターンする値は、varの永続的な値となる。

以下は例である:

(defvar foo (lazy-completion-table foo make-my-alist))

既存の補完テーブルを受け取り変更したバージョンをリターンする関数が、いくつかあります。completion-table-case-foldは大文字小文字を区別しない、case-insensitiveなテーブルをリターンします。completion-table-in-turnとcompletion-table-mergeは、複数の入力テーブルを、異なる方法で組み合わせます。completion-table-subvertはテーブルを異なる初期プレフィックス(initial prefix)で変更します。completion-table-with-quotingはクォートされたテキストの処理に適したテーブルをリターンします。completion-table-with-predicateは述語関数(predicate function)によりフィルターします。completion-table-with-terminatorは終端文字列(terminating string)を追加します。

20.6.2 補完とミニバッファー

このセクションでは、補完つきでミニバッファーから読み取るための、基本的なインターフェイスを説明します。

Function: completing-read prompt collection &optional predicate require-match initial history default inherit-input-method

この関数は、補完の提供によりユーザーを支援して、ミニバッファーから文字列を読み取る。prompt(文字列でなければならない)のプロンプトとともに、ミニバッファーをアクティブ化する。

実際の補完は、補完テーブルcollectionと補完述語predicateを関数try-completion(基本的な補完関数を参照)に渡すことにより行われる。これは補完の使用されるローカルキーマップに特定のコマンドをバインドしたとき発生する。これらのコマンドのいくつかは、test-completionも呼び出す。したがって、predicateが非nilの場合は、collectionとcompletion-ignore-caseが矛盾しないようにすべきである。Definition of test-completionを参照のこと。

See section プログラムされた補完, for detailed requirements when collection is a function.

オプション引数require-matchの値は、ユーザーがミニバッファーをexitする方法を決定する。

nilの場合、通常のミニバッファーexitコマンドは、ミニバッファーの入力と無関係に機能する。
tの場合は、入力がcollectionの要素に補完されるまで、通常のミニバッファーexitコマンドは機能しない。
confirmの場合、どのような入力でもユーザーはexitできるが、入力がconfirmの要素に補完されていなければ、確認を求められる。
confirm-after-completionの場合、どのような入力でもユーザーはexitできるが、前のコマンドが補完コマンド(たとえばminibuffer-confirm-exit-commandsの中のコマンドの1つの場合)で、入力の結果がcollectionの要素でない場合は、確認を求められる。補完を行うミニバッファーコマンドを参照のこと。
require-matchにたいする他の値はtと同じふぁが、exitコマンドは補完処理中はexitしない。

しかし、require-matchの値に関わらず、空の入力は常に許される。この場合、completing-readはdefaultがリストなら最初の要素、defaultがnilなら""、またはdefaultをリターンする。文字列およびdefault内の文字列は、ヒストリーコマンドを通じてユーザーが利用できる。

関数completing-readはrequire-matchがnilの場合はキーマップとしてminibuffer-local-completion-mapを、require-matchが非nilの場合はminibuffer-local-must-match-mapを使用する。補完を行うミニバッファーコマンドを参照のこと。

引数historyは入力の保存とミニバッファーヒストリーコマンドに、どのヒストリーリスト変数を使用するか指定する。デフォルトはminibuffer-history。ミニバッファーのヒストリーを参照のこと。

initialは、ほとんどの場合推奨されない。historyにたいするコンスセル指定と組み合わせた場合のみ、非nil値の使用を推奨する。入力の初期値を参照のこと。デフォルト入力にたいしては、かわりにdefaultを使用する。

変数completion-ignore-caseが非nilの場合、利用可能なマッチにたいして入力を比較するときの補完は、大文字小文字を区別しない。基本的な補完関数を参照のこと。このモードでの操作では、predicateも大文字小文字を区別してはならない(さもないと驚くべき結果となるであろう)。

以下はcompleting-readを使用した例である:

(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; 前の式を評価後に、
;;   ミニバッファーに以下が表示される。:

---------- Buffer: Minibuffer ----------
Complete a foo: fo∗
---------- Buffer: Minibuffer ----------

その後ユーザーがDEL DEL b RETをタイプすると、completing-readはbarfooをリターンする。

completing-read関数は、実際に補完を行うコマンドの情報を渡すために、変数をバインドする。これらの変数は、以降のセクションで説明する。

Variable: completing-read-function: この変数の値は関数でなければならず、補完つきの読み取りを実際に行うためにcompleting-readから呼び出される。この関数はcompleting-readと同じ引数を受け入れる。他の関数のバインドして、通常のcompleting-readの振る舞いを完全にオーバーライドすることができる。

20.6.3 補完を行うミニバッファーコマンド

このセクションでは、補完のためにミニバッファーで使用されるキーマップ、コマンド、ユーザーオプションを説明します。

Variable: minibuffer-completion-table: この変数の値は、ミニバッファー内の補完に使用される補完テーブルである。これはcompleting-readがtry-completionに渡す補完テーブルを含むグローバル変数である。minibuffer-complete-wordのような、ミニバッファー補完コマンドにより使用される。

Variable: minibuffer-completion-predicate: この変数の値はcompleting-readがtry-completionに渡す述語(predicate)である。この変数は、他のミニバッファー補完関数でも使用される。

Variable: minibuffer-completion-confirm: この変数はミニバッファーをexitする前に、Emacsが確認を求めるかどうかを決定する。completing-readはこの変数をバインドして、exitする前に関数minibuffer-complete-and-exitがこの値をチェックする。値がnilの場合は、確認は求められない。値がconfirmの場合、入力が有効な補完候補でなくてもユーザーはexitするかもしれないが、Emacsは確認を求めない。値がconfirm-after-completionの場合、入力が有効な補完候補でなくてもユーザーはexitするかもしれないが、ユーザーがminibuffer-confirm-exit-commands内の任意の補完コマンドの直後に入力を確定した場合、Emacsは確認を求める。

Variable: minibuffer-confirm-exit-commands: この変数には、completing-readの引数require-matchがconfirm-after-completionの場合は、ミニバッファーをexitする前にEmacsが確認を求めるようにさせるコマンドのリストが保持されている。このリストないのコマンドを呼び出した直後にユーザーがミニバッファーのexitを試みると、Emacsは確認を求める。

Command: minibuffer-complete-word: この関数は、ただ1つの単語からミニバッファーを補完する。たとえミニバッファーのコンテンツが1つの補完しかもたない場合でも、minibuffer-complete-wordはその単語に属さない最初の文字を超えた追加はしない。構文テーブルを参照のこと。

Command: minibuffer-complete: この関数は、可能な限りミニバッファーのコンテンツを補完する。

Command: minibuffer-complete-and-exit: この関数はミニバッファーのコンテンツを補完して、確認が要求されない場合(たとえばminibuffer-completion-confirmがnilのとき)はexitする。確認が要求される場合には、このコマンドを即座に繰り返すことにより確認が行われないようにする。このコマンドは2回連続で実行された場合は確認なしで機能するようにプログラムされている。

Command: minibuffer-completion-help: この関数は、カレントのミニバッファーのコンテンツで利用可能な補完のリストを作成する。これはall-completionsの引数collectionに変数minibuffer-completion-tableの値を、引数predicateにminibuffer-completion-predicateの値を使用して呼び出すことにより機能する。補完リストは、*Completions*と呼ばれるバッファーのテキストとして表示される。

Function: display-completion-list completions

この関数はstandard-output内のストリーム(通常はバッファー)にcompletionsを表示する(ストリームについての詳細は、Lispオブジェクトの読み取りとプリントを参照)。引数completionsは通常、all-completionsがリターンする補完リストそのものだが、それである必要はない。要素はシンボルか文字列で、どちらも単にプリントされる。文字列2つのリストでもよく、2つの文字列が結合されたかのようにプリントされる。この場合、1つ目の文字列は実際の補完で、2つ目の文字列は注釈の役目を負う。

この関数はminibuffer-completion-helpにより呼び出される。一般的には、以下のようにwith-output-to-temp-bufferとともに使用される。

(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
    (all-completions (buffer-string) my-alist)))

User Option: completion-auto-help: この変数が非nilの場合には、次の文字が一意でないために決定できず補完が完了しないときは常に、補完コマンドは利用可能な補完リストを自動的に表示する。

Variable: minibuffer-local-completion-map

completing-readの値は、補完の1つが完全に一致することを要求されないときにローカルキーマップとして使用される。デフォルトでは、このキーマップは以下のバインディングを作成する:

?: minibuffer-completion-help
SPC: minibuffer-complete-word
TAB: minibuffer-complete

親キーマップとしてminibuffer-local-mapを使用する(Definition of minibuffer-local-mapを参照)。

Variable: minibuffer-local-must-match-map

completing-readは、補完の1つの完全な一致が要求されないときのローカルキーマップとして、この値を使用する。したがってexit-minibufferにキーがバインドされていなければ、無条件にミニバッファーをexitする。デフォルトでは、このキーマップは以下のバインディングを作成する:

C-j: minibuffer-complete-and-exit
RET: minibuffer-complete-and-exit

親キーマップはminibuffer-local-completion-mapを使用する。

Variable: minibuffer-local-filename-completion-map: これは単にSPCを非バインドするsparseキーマップ(sparse: 疎、希薄、まばら)を作成する。これはファイル名にスペースを含めることができるからである。関数read-file-nameは、このキーマップとminibuffer-local-completion-mapかminibuffer-local-must-match-mapのいずれかを組み合わせる。

20.6.4 高レベルの補完関数

このセクションでは、特定の種類の名前を補完つきで読み取る便利な高レベル関数を説明します。

ほとんどの場合、Lisp関数の中盤でこれらの関数を呼び出すべきではありません。可能なときは、interactive指定の内部で呼び出し、ミニバッファーのすべての入力をコマンドの引数読み取りの一部にします。コマンドの定義を参照してください。

Function: read-buffer prompt &optional default require-match predicate

This function reads the name of a buffer and returns it as a string. It prompts with prompt. The argument default is the default name to use, the value to return if the user exits with an empty minibuffer. If non-nil, it should be a string, a list of strings, or a buffer. If it is a list, the default value is the first element of this list. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input.

引数promptは、コロンかスペースで終わる文字列である。defaultが非nilの場合、この関数はデフォルト値つきでミニバッファーから読み取る際の慣習にしたがい、コロンの前のpromptの中にこれを挿入する。

オプション引数require-matchは、completing-readのときと同じ。補完とミニバッファーを参照のこと。

The optional argument predicate, if non-nil, specifies a function to filter the buffers that should be considered: the function will be called with every potential candidate as its argument, and should return nil to reject the candidate, non-nil to accept it.

以下の例で、ユーザーが‘minibuffer.t’とエンターしてから、RETをタイプする。引数require-matchはtであり、与えられた入力で始まるバッファー名は‘minibuffer.texi’だけなので、その名前が値となる。

(read-buffer "Buffer name: " "foo" t)

;; 前の式を評価した後、
;;   空のミニバッファーに
;;   以下のプロンプトが表示される:

---------- Buffer: Minibuffer ----------
Buffer name (default foo): ∗
---------- Buffer: Minibuffer ----------

;; ユーザーがminibuffer.t RETとタイプする。
     ⇒ "minibuffer.texi"

User Option: read-buffer-function: この変数が非nilの場合は、バッファー名を読み取る関数である。read-bufferは通常行うことを行うかわりに、read-bufferと同じ引数でその関数を呼び出す。

User Option: read-buffer-completion-ignore-case: If this variable is non-nil, read-buffer ignores case when performing completion while reading the buffer name.

Function: read-command prompt &optional default

この関数はコマンドの名前を読み取り、Lispシンボルとしてそれをリターンする。引数promptは、read-from-minibufferで使用される場合と同じ。それが何であれcommandpがtをリターンすればコマンドであり、コマンド名とはcommandpがtをリターンするシンボルだということを思い出してほしい。interactiveな呼び出しを参照のこと。

引数defaultは、ユーザーがnull入力をエンターした場合に何をリターンするか指定する。シンボル、文字列、文字列リストを指定できる。文字列の場合、read-commandはリターンする前にそれをinternする。リストの場合、read-commandはリストの最初の要素をinternする。defaultがnilの場合は、デフォルトが指定されなかったことを意味する。その場合もしユーザーがnull入力をエンターすると、リターン値は(intern "")、つまり名前が空文字列のシンボルとなる。

(read-command "Command name? ")

;; 前の式を評価した後に、
;;   空のミニバッファーに以下のプロンプトが表示される:

---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------

ユーザーがforward-c RETとタイプした場合、この関数はforward-charをリターンする。

read-command関数は、completing-readの簡略化されたインターフェイスである。実在するLisp変数のセットを補完するために変数obarrayを、コマンド名だけを受け入れるために述語commandpを使用する。

(read-command prompt)
≡
(intern (completing-read prompt obarray
                         'commandp t nil))

Function: read-variable prompt &optional default: この変数はカスタマイズ可能な変数の名前を読み取り、それをシンボルとしてリターンする。引数の形式はread-commandの引数と同じ。この関数は、commandpのかわりにcustom-variable-pを述語に使用する点を除き、read-commandと同様に振る舞う。

Command: read-color &optional prompt convert allow-empty display

この関数はカラー指定(カラー名、または#RRRGGGBBBのような形式のRGB16進値)の文字列を読み取る。これはプロンプトにprompt(デフォルトは"Color (name or #RGB triplet):")を表示して、カラー名にたいする補完を提供する(16進RGB値は補完しない)。標準的なカラー名に加えて、補完候補にはポイント位置のフォアグラウンドカラーとバックグラウンドカラーが含まれる。

Valid RGB values are described in カラー名.

この関数のリターン値は、ミニバッファー内でユーザーがタイプした文字列である。しかし、インタラクティブに呼び出されたとき、またはオプション引数convertが非nilの場合は、入力されたカラー名のかわりに、それに対応するRGB値文字列をリターンする。この関数は、入力に有効なカラー指定を求める。allow-emptyが非nilでユーザーがnull入力をエンターした場合は、空のカラー名が許される。

インタラクティブに呼び出されたとき、またはdisplayが非nilの場合には、エコーエリアにもリターン値が表示される。

ユーザー選択のコーディングシステムの関数read-coding-systemとread-non-nil-coding-system、および入力メソッドのread-input-method-nameも参照のこと。

20.6.5 ファイル名の読み取り

高レベル補完関数read-file-name、read-directory-name、read-shell-commandはそれぞれ、ファイル名、ディレクトリー名、シェルコマンドを読み取るようデザインされています。これらはデフォルトディレクトリーの自動挿入を含む特別な機能を提供します。

Function: read-file-name prompt &optional directory default require-match initial predicate

この関数はプロンプトpromptとともに補完つきでファイル名を読み取る。

例外として以下のすべてが真ならば、この関数はミニバッファーのかわりにグラフィカルなファイルダイアログを使用してファイル名を読み取る:

マウスコマンドを通じて呼び出された。
グラフィカルなディスプレイ上の選択されたフレームがこの種のダイアログをサポートする。
変数use-dialog-boxが非nilの場合。Dialog Boxes in The GNU Emacs Manualを参照のこと。
directory引数(以下参照)がリモートファイルを指定しない。Remote Files in The GNU Emacs Manualを参照のこと。

グラフィカルなファイルダイアログを使用したときの正確な振る舞いは、プラットホームに依存する。ここでは単にミニバッファーを使用したときの振る舞いを記す。

read-file-name does not automatically expand the returned file name. You can call expand-file-name yourself if an absolute file name is required.

オプション引数require-matchは、completing-readのときと同じ。補完とミニバッファーを参照のこと。

引数directoryは、相対ファイル名の補完に使用するディレクトリーを指定する。値は絶対ディレクトリー名。変数insert-default-directoryが非nilの場合は、初期入力としてミニバッファーにdirectoryも挿入される。デフォルトはカレントバッファーのdefault-directoryの値。

initialを指定した場合、それはミニバッファーに挿入する初期ファイル名になる(directoryが挿入された場合はその後に挿入される)。この場合、ポイントはinitialの先頭に配される。initialのデフォルト値はnil(ファイル名を挿入しない)。initialが何を行うか確認するには、ファイルをvisitしているバッファーでC-x C-vを試すとよい。注意: ほとんどの場合、initialよりもdefaultの使用を推奨する。

defaultが非nilの場合、ユーザーが最初にread-file-nameが挿入したものと同じ、空以外のコンテンツを残してミニバッファーをexitすると、この関数はdefaultをリターンする。insert-default-directoryが非nilの場合はそれがデフォルトとなるので、ミニバッファーの初期コンテンツは常に空以外になる。require-matchの値に関わらず、defaultの有効性はチェックされない。とはいえrequire-matchが非nilの場合、ミニバッファーの初期コンテンツは有効なファイル名(またはディレクトリー名)であるべきだろう。それが有効でない場合、ユーザーがそれを編集せずにexitするとread-file-nameは補完を試み、defaultはリターンされない。defaultはヒストリーコマンドからも利用できる。

defaultがnilの場合、read-file-nameはその場所に代用するデフォルトを探そうと試みる。この代用デフォルトは、明示的にdefaultにそれが指定されたかのように、defaultとまったく同じ方法で扱われる。defaultがnilでもinitialが非nilの場合、デフォルトはdirectoryとinitialから得られる絶対ファイル名になる。defaultとinitialの両方がnilで、そのバッファーがファイルをvisitしているバッファーの場合、read-file-nameはそのファイルの絶対ファイル名をデフォルトとして使用する。バッファーがファイルをvisitしていなければ、デフォルトは存在しない。この場合、ユーザーが編集せずにRETをタイプすると、read-file-nameは前にミニバッファーに挿入されたコンテンツを単にリターンする。

空のミニバッファー内でユーザーがRETをタイプした場合、この関数はrequire-matchの値に関わらず、空の文字列をリターンする。たとえばユーザーがM-x set-visited-file-nameを使用して、カレントバッファーをファイルをvisitしていないことにするのに、この方法を使用している。

predicateが非nilの場合、それは補完候補として許容できるファイル名を決定する、1引数の関数である。predicateが関数名にたいして非nilをリターンすれば、それはファイル名として許容できる値である。

以下はread-file-nameを使用した例である:

(read-file-name "The file is ")

;; 前の式を評価した後に、
;;   ミニバッファーに以下が表示される。:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/∗
---------- Buffer: Minibuffer ----------

manual TABをタイプすると以下がリターンされる:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi∗
---------- Buffer: Minibuffer ----------

ここでユーザーがRETをタイプすると、read-file-nameは文字列"/gp/gnu/elisp/manual.texi"をファイル名としてリターンする。

Variable: read-file-name-function: 非nilの場合は、read-file-nameと同じ引数を受け取る関数である。read-file-nameが呼び出されたとき、read-file-nameは通常の処理を行なうかわりに、与えられた引数でこの関数を呼び出す。

User Option: read-file-name-completion-ignore-case: この変数が非nilの場合、read-file-nameは補完を行なう際に大文字小文字を無視する。

Function: read-directory-name prompt &optional directory default require-match initial

この関数はread-file-nameと似ているが、補完候補としてディレクトリーだけを許す。

defaultがnilでinitialが非nilの場合、read-directory-nameはdirectory(directoryがnilならカレントバッファーのデフォルトディレクトリー)とinitialを組み合わせて代替えのデフォルトを構築する。defaultとinitialの両方がnilの場合、この関数はdirectory、directoryもnilの場合はカレントバッファーのデフォルトディレクトリーを代替えのデフォルトとして使用する。

User Option: insert-default-directory

この変数はread-file-nameにより使用されるため、ファイル名を読み取るほとんどのコマンドにより、間接的に使用される。(これらのコマンドにはコマンドのインタラクティブフォームに‘f’や‘F’のコードレター(code letter))をふくむすべてのコマンドが含まれる。Code Characters for interactiveを参照のこと。)この変数の値は、(もしあれば)デフォルトディレクトリー名をミニバッファー内に配してread-file-nameを開始するかどうかを制御する。変数の値がnilの場合、read-file-nameはミニバッファーに初期入力を何も配さない(ただしinitial引数で初期入力を指定しない場合)。この場合、依然としてデフォルトディレクトリーが相対ファイル名の補完に使用されるが、表示はされない。

この変数がnilでミニバッファーの初期コンテンツが空の場合、ユーザーはデフォルト値にアクセスするために次のヒストリー要素を明示的にフェッチする必要があるだろう。この変数が非nilならミニバッファーの初期コンテンツは常に空以外となり、ミニバッファーで編集をおこなわず即座にRETをタイプすることにより、常にデフォルト値を要求できる(上記参照)。

たとえば:

;; デフォルトディレクトリーとともにミニバッファーが開始。
(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/∗
---------- Buffer: Minibuffer ----------

;; ミニバッファーはプロンプトだけで空。
;;   appears on its line.
(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ∗
---------- Buffer: Minibuffer ----------

Function: read-shell-command prompt &optional initial history &rest args

この関数は、プロンプトpromptと優れた補完を提供して、ミニバッファーからのシェルコマンドを読み取る。これはコマンド名にたいして適切な候補を使用してコマンドの最初の単語を補完する。コマンドの残りの単語はファイル名として補完する。

この関数はミニバッファー入力にたいするキーマップとしてminibuffer-local-shell-command-mapを使用する。history引数は使用するヒストリーリストを指定する。省略、またはnilの場合のデフォルトはshell-command-history(shell-command-historyを参照)。オプション引数initialはミニバッファーの初期コンテンツを指定する(入力の初期値を参照)。もしあれば、残りのargsはread-from-minibuffer内のdefaultおよびinherit-input-methodとして使用される(ミニバッファーでのテキスト文字列の読み取りを参照)。

Variable: minibuffer-local-shell-command-map: このキーマップはread-shell-commandにより、コマンドおよびシェルコマンドの一部となるファイル名の補完のために使用される。これは親キーマップとしてminibuffer-local-mapを使用し、TABをcompletion-at-pointにバインドする。

20.6.6 補完変数

補完のデフォルト動作を変更するために使用される変数がいくつかあります。

User Option: completion-styles: この変数の値は、補完を行うために使用される補完スタイル(シンボル)である。補完スタイル(completion style)とは、補完を生成するためのルールセットのこと。このリストにあるシンボルはそれぞれ、completion-styles-alist内に対応するエントリーをもたなければならない。

Variable: completion-styles-alist

この変数には補完スタイルのリストが格納される。リスト内の各要素は以下の形式をもつ

(style try-completion all-completions doc)

ここでstyleは補完スタイルの名前(シンボル)であり、そのスタイルを参照するために変数completion-styles内で使用されるかもしれない。try-completionは補完を行なう関数で、all-completions補完をリストする関数、doc補完スタイルを説明する文字列である。

関数try-completionおよびall-completionsはstring、collection、predicate、pointの4つの引数をとる。引数string、collection、predicateの意味はtry-completion(基本的な補完関数を参照)のときと同様。引数pointはstring内のポイント位置。各関数は自身の処理を行った場合は非nilを、行わなかった場合(たとえば補完スタイルに一致するようにstringを行う方法がない場合)はnilをリターンする。

ユーザーがminibuffer-complete(補完を行うミニバッファーコマンドを参照)のような補完コマンドを呼び出すと、Emacsはcompletion-stylesに最初にリストされたスタイルを探して、そのスタイルのtry-completion関数を呼び出す。この関数がnilをリターンした場合、Emacsは次にリストされた補完スタイルに移動してそのスタイルのtry-completion関数を呼び出すといったように、try-completion関数の1つが補完の処理に成功して非nil値をリターンするまで順次これを行なう。同様の手順はall-completions関数を通じて、補完のリストにも行われる。

利用できる補完スタイルについてはCompletion Styles in The GNU Emacs Manualを参照のこと。

User Option: completion-category-overrides

この変数は特別な補完スタイルと、特定の種類のテキスト補完時に使用するその他の補完動作を指定する。この変数の値は(category . alist)という形式の要素をもつalistである。categoryは何が補完されるかを記述するシンボルで、現在のところカテゴリーにbuffer、file、unicode-nameが定義されているが、これに特化した補完関数(プログラムされた補完を参照)を通じて他のカテゴリーを定義できる。alistは、そのカテゴリーにたいして補完がどのように振る舞うべきかを記述する連想リスト。以下のalistのキーがサポートされる:

styles: 値は補完スタイル(シンボル)のリスト。
cycle: 値はそのカテゴリーにたいするcompletion-cycle-threshold(Completion Options in The GNU Emacs Manualを参照)の値。

将来、さらにalistエントリーが定義されるかもしれない。

Variable: completion-extra-properties

この変数はカレント補完コマンドの特別なプロパティの指定に使用される。この変数は補完に特化したコマンドによりletバインドされることを意図している。値はプロパティ/値ペアーのリスト。以下のプロパティがサポートされる:

:annotation-function: 値は補完バッファー内に注釈(annotation)を加える関数。この関数は引数completionを1つ受け取りnil、または補完の隣に表示する文字列をリターンしなければならない。
:exit-function: 値は補完を行った後に実行する関数。この関数は2つの引数stringとstatusを受け取る。stringは補完されたフィールドのテキストで、statusは行われた操作の種類を示す。操作の種類は、テキストの補完が完了したならfinished、それ以上補完できないが補完が完了していなければsole、有効な補完だがさらに補完できるときはexactとなる。

20.6.7 プログラムされた補完

意図した利用可能な補完のすべてを含むalistまたはobarrayを前もって作成するのが不可能または不便なことがあります。このような場合は、与えられた文字列にたいする補完を計算する独自の関数を提供できます。これはプログラム補完(programmed completion)と呼ばれます。Emacsは数あるケースの中でも特に、ファイル名の補完(ファイル名の補完を参照)でプログラム補完を使用しています。

この機能を使用するためには、関数をcompleting-readのcollection引数に渡します。関数completing-readはその補完関数がtry-completion、all-completionsなどの基本的な補完関数に渡されて、その関数がすべてを行えるよう取り計らいます。

補完関数は3つの引数を受け取ります:

補完される文字列。
利用可能なマッチをフィルターする述語関数。もしなければnil。関数は利用可能なマッチにたいしてこの述語(predicate)を呼び出し、述語がnilをリターンした場合はそのマッチを無視する。
A flag specifying the type of completion operation to perform. This flag may be one of the following values.

nil

try-completionを指定する。関数は指定された文字が一意かつ完全一致の場合は、tをリターンする。マッチが複数の場合、すべてのマッチに共通する部分文字列をリターンする(文字列が補完候補の1つに完全一致するが、より長い他の候補にもマッチする場合、リターン値はその文字列)。マッチがなければnilをリターンする。

t

all-completionsを指定する。関数は指定された文字列の利用可能なすべての補完のリストをリターンする。

lambda

test-completionを指定する。関数は指定された文字列がいくつかの補完候補に完全一致する場合はt、それ以外はnilをリターンする。

(boundaries . suffix)

completion-boundariesを指定する。関数は(boundaries start . end)をリターンする。ここでstartは指定された文字列内の境界の開始位置、endはsuffix内の境界の終了位置。

metadata

カレント補完の状態に関する情報の要求を指定する。リターン値は(metadata . alist)の形式をもち、alistは以下で説明する要素をもつ連想配列。

フラグに他の値が指定された場合、補完関数はnilをリターンする。

以下はmetadataフラグ引数への応答として補完関数がリターンするかもしれない、metadataエントリーのリストです:

category: 値は補完関数が補完を試みているテキストの種類を説明するシンボル。シンボルがcompletion-category-overrides内のキーの1つにマッチする場合、通常の補完動作はオーバーライドされる。補完変数を参照のこと。
annotation-function: 値は補完に注釈(annotation)を付ける関数。この関数は1つの引数stringをとり、これは利用可能な補完である。リターン値は文字列で、*Completions*バッファー内の補完stringの後に表示される。
display-sort-function: 値は補完をソートする関数。関数は1つの引数をとる。これは補完文字列のリストで、ソートされた補完文字列リストがリターンされる。その入力のリストは破壊的に変更することが許される。
cycle-sort-function: 値はcompletion-cycle-thresholdが非nilで、ユーザーが補完候補を巡回するときに補完をソートする関数。引数のリストとリターン値はdisplay-sort-functionと同様。

Function: completion-table-dynamic function &optional switch-buffer

This function is a convenient way to write a function that can act as a programmed completion function. The argument function should be a function that takes one argument, a string, and returns an alist of possible completions of it. It is allowed to ignore the argument and return a full list of all possible completions. You can think of completion-table-dynamic as a transducer between that interface and the interface for programmed completion functions.

If the optional argument switch-buffer is non-nil, and completion is performed in the minibuffer, function will be called with current buffer set to the buffer from which the minibuffer was entered.

Function: completion-table-with-cache function &optional ignore-case: これは前回の引数/結果ペアーを保存するcompletion-table-dynamicにたいするラッパーである。これは同じ引数にたいする複数回の検査に必要なのは、1回のfunction呼び出しだけであることを意味する。これは外部プロセス呼び出しなど、処理が低速のとき有用かもしれない。

20.6.8 通常バッファーでの補完

補完は通常はミニバッファー内で行われますが、補完機能は通常のEmacsバッファー内のテキストにも使用できます。多くのメジャーモードで、コマンドC-M-iまたはM-TABによりバッファー内補完が行われ、それらはcompletion-at-pointにバインドされています。Symbol Completion in The GNU Emacs Manualを参照してください。このコマンドはアブノーマルフック変数completion-at-point-functionsを使用します:

Variable: completion-at-point-functions

このアブノーマルフックの値は関数のリストである。これらの関数はポイント位置のテキストの補完にたいする補完テーブルの計算に使用される。これはメジャーモードにより、モード特有な補完テーブル(メジャーモードの慣習を参照)の提供に使用できる。

When the command completion-at-point runs, it calls the functions in the list one by one, without any argument. Each function should return nil unless it can and wants to take responsibility for the completion data for the text at point. Otherwise it should return a list of the following form:

(start end collection . props)

ここでstartとendは補完する(ポイントを取り囲む)テキストの区切りである。collectionはそのテキストを補完する補完テーブルであり、try-completion(基本的な補完関数を参照)の2つ目の引数として渡すのに適した形式である。補完候補はcompletion-styles(補完変数を参照)で定義された補完スタイルを通じ、この補完テーブルを通常の方法で使用して生成されるだろう。propsは追加の情報のためのプロパティリストである。completion-extra-properties内のすべてのプロパティ(補完変数を参照)と、以下の追加のプロパティが認識される:

:predicate: 値は補完候補が満足する必要がある述語。
:exclusive: 値がnoの場合は、もし補完テーブルがポイント位置のテキストのマッチに失敗したなら、補完の失敗を報告するかわりにcompletion-at-pointはcompletion-at-point-functions内の次の関数へ移動する。

The functions on this hook should generally return quickly, since they may be called very often (e.g., from post-command-hook). Supplying a function for collection is strongly recommended if generating the list of completions is an expensive operation. Emacs may internally call functions in completion-at-point-functions many times, but care about the value of collection for only some of these calls. By supplying a function for collection, Emacs can defer generating completions until necessary. You can use completion-table-dynamic to create a wrapper function:

;; Avoid this pattern.
(let ((beg ...) (end ...) (my-completions (my-make-completions)))
  (list beg end my-completions))

;; Use this instead.
(let ((beg ...) (end ...))
  (list beg
        end
        (completion-table-dynamic
          (lambda (_)
            (my-make-completions)))))

Additionally, the collection should generally not be pre-filtered based on the current text between start and end, because that is the responsibility of the caller of completion-at-point-functions to do that according to the completion styles it decides to use.

A function in completion-at-point-functions may also return a function instead of a list as described above. In that case, that returned function is called, with no argument, and it is entirely responsible for performing the completion. We discourage this usage; it is only intended to help convert old code to using completion-at-point.

非nil値を最初にリターンしたcompletion-at-point-functions内の関数が、completion-at-pointにより使用される。残りの関数は呼び出されない。これの例外は上述の:exclusive指定があるときである。

以下の関数は、Emacsバッファー内の任意に拡張されたテキストにたいして便利な補完方法を提供します:

Function: completion-in-region start end collection &optional predicate

この関数はcollectionを使用して、カレントバッファー内の位置startとendの間のテキストを補完する。引数collectionはtry-completion(基本的な補完関数を参照)のときと同じ意味をもつ。

この関数は補完テキストを直接カレントバッファーに挿入する。completing-read(補完とミニバッファーを参照)とは異なり、ミニバッファーをアクティブにしない。

この関数が機能するためには、ポイントがstartとendの間になければならない。

20.7 Yes-or-Noによる問い合わせ

このセクションでは、ユーザーにyes-or-noの確認を求める関数を説明します。関数y-or-n-pは1文字での応答に使用できます。この関数は不注意による誤った答えが深刻な結果を招かない場合に有用です。yes-or-no-pは3文字から4文字の答えを要求するので、より重大な問に適しています。

3つの関数はどれも、マウスを使用して呼び出されたコマンド、より正確にはlast-nonmenu-event(コマンドループからの情報を参照)がnilかリストの場合は、問いに答えるためにダイアログボックスまたはポップアップメニューを使用します。それ以外の場合はキーボード入力を使用します。呼び出しの周囲でlast-nonmenu-eventに適切な値をバインドすることにより、マウスまたはキーボードの使用を強制できます。

厳密に言うと、yes-or-no-pはミニバッファーを使用し、y-or-n-pは使用しませんが、これらのコマンドは一緒に説明したほうがよいでしょう。

Function: y-or-n-p prompt

This function asks the user a question, expecting input in the echo area. It returns t if the user types y, nil if the user types n. This function also accepts SPC to mean yes and DEL to mean no. It accepts C-] to quit, like C-g, because the question might look like a minibuffer and for that reason the user might try to use C-] to get out. The answer is a single character, with no RET needed to terminate it. Upper and lower case are equivalent.

“答えを尋ねる”とはエコーエリアにpromptと、その後に文字列‘(y or n) ’をプリントすることを意味する。期待される答え(y、n、SPC、DEL、もしくは質問を終了するその他のキー)以外が入力された場合、この関数は‘Please answer y or n.’と応答し、繰り返し答えの入力を要求する。

この関数は答えの編集を許さないため、実際にミニバッファーは使用しない。実際に使用するのはミニバッファーと同じスクリーンスペースを使用するエコーエリア(エコーエリアを参照)である。問いが答えられるまで、カーソルはエコーエリアに移動する。

答えとその意味は、たとえ‘y’と‘n’であっても固定されたものではなく、キーマップquery-replace-mapにより指定される(検索と置換を参照)。特にユーザーがrecenter、scroll-up、scroll-down、scroll-other-window、scroll-other-window-down(それぞれquery-replace-map内でC-l、C-v、M-v、C-M-v、C-M-S-vにバインドされている)のような特殊な応答をエンターした場合、この関数はは指定されたウィンドウの再センタリングやスクロール操作を処理してから再度答えを求める。

例ではエコーエリアのメッセージを連続する行で示しているが、スクリーン上に実際に表示されるのは1回に1行だけである。

Function: y-or-n-p-with-timeout prompt seconds default: y-or-n-pと同様だが、ユーザーがseconds秒以内に答えないと、この関数は待つのをやめてdefaultをリターンする。これはタイマーをセットアップすることにより機能する。引数secondsは数字である。

Function: yes-or-no-p prompt

この関数は質問して、ミニバッファーに答えの入力を求める。これはユーザーが‘yes’をエンターするとtを、‘no’をエンターするとnilをリターンする。ユーザーは応答を終えるためにRETをタイプしなければならない。大文字と小文字は等価である。

yes-or-no-pはエコーエリアにpromptとその後に‘(yes or no) ’を表示することにより開始される。ユーザーは期待される応答の1つをタイプしなければならない。それ以外の答えだと、この関数は‘Please answer yes or no.’と応答して約2秒待った後に要求を繰り返す。

yes-or-no-pはy-or-n-pより多くの作業をユーザーに要求し、より重大な決定に適している。

以下は例である:

(yes-or-no-p "Do you really want to remove everything? ")

;; 前の式を評価した後、
;;   空のミニバッファーに
;;   以下のプロンプトが表示される:

---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------

ユーザーが最初にy RETとタイプした場合、これは無効である。なぜならこの関数は‘yes’という単語全体を要求しているので、以下のプロンプトを説明のために一時停止して表示する。

---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------

20.8 複数のY-or-Nの問い合わせ

When you have a series of similar questions to ask, such as “Do you want to save this buffer?” for each buffer in turn, you should use map-y-or-n-p to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once.

Function: map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area

この関数はユーザーに一連の質問をし、それぞれの質問にたいしてエコーエリア内の1文字の答えを読み取る。

値listは質問をするオブジェクトを指定する。これはリスト、オブジェクト、または生成関数(generator function)のいずれかである。関数の場合は引数なしで、次に質問するオブジェクト、または質問の中止を意味するnilのいずれかをリターンする。

引数prompterは各質問について問い合わせ方法を指定する。prompterが文字列の場合、質問テキストは以下のようになる:

(format prompter object)

ここでobjectは、(listから得られる)質問する次のオブジェクトである。

文字列でない場合、prompterは1つの引数(質問する次のオブジェクト)をとる関数で、質問テキストをリターンする。値が文字列の場合は、ユーザー問うための質問。関数はt(ユーザーに尋ねずこのオブジェクトを処理する)、またはnil(ユーザーに尋ねずこのオブジェクトを無視する)をリターンすることもできる。

引数actorは、ユーザーが与えた答えにたいし、どのように処理するかを指定する。これは引数が1つの関数で、ユーザーがyesと答えたオブジェクトを引数に呼び出される。引数は常にlistから取得したオブジェクトである。

引数helpが与えられた場合は、以下の形式のリストである:

(singular plural action)

singularはそのオブジェクトが概念的に何に作用するかを説明する単数形の名詞を含む文字列、pluralはそれに対応する複数形の名詞、actionはactorが何を行うかを説明する他動詞である。

helpを指定しない場合のデフォルトは、("object" "objects" "act on")。

質問のたびに、ユーザーはそのオブジェクトを処理するにはy、YまたはSPCを、そのオブジェクトをスキップするにはn、N、またはDELを、以降のすべてのオブジェクトを処理するには!を、exit(以降のすべてのオブジェクトをスキップ)するにはESCかqを、カレントオブジェクトを処理した後にexitするには.(ピリオド)を、ヘルプを入手するにはC-hをエンターする。これらはquery-replaceが受け入れるのと同じ答えである。キーマップquery-replace-mapはmap-y-or-n-pにたいするそれらの意味を定義し、query-replaceにたいしても同様に定義する。検索と置換を参照のこと。

action-alistを使用して、利用できる追加の答えとそれらが何を意味するかを指定できる。これは要素が(char function help)という形式のalistで、それぞれの要素が追加の答えを1つ定義する。要素の内容はcharが文字(答え)、functionが引数が1つ(listから取得するオブジェクト)の関数、helpが文字列である。

When the user responds with char, map-y-or-n-p calls function. If it returns non-nil, the object is considered acted upon, and map-y-or-n-p advances to the next object in list. If it returns nil, the prompt is repeated for the same object.

確認を求める間は通常、map-y-or-n-pはcursor-in-echo-areaをバインドする。しかしno-cursor-in-echo-areaが非nilの場合はバインドしない。

マウスを使用して呼び出されたコマンドからmap-y-or-n-pが呼び出された場合(より正確にはlast-nonmenu-eventは非nilかリストの場合。コマンドループからの情報を参照)は、確認を求めるためにダイアログボックスかポップアップメニューが使用される。この場合、キーボード入力やエコーエリアは使用されない。呼び出しの前後でlast-nonmenu-eventを適切な値にバインドして、入力マウスあるいはキーボードの入力を強制できる。

map-y-or-n-pのリターン値は、処理したオブジェクトの数である。

20.9 パスワードの読み取り

他のプログラムに渡すためのパスワードを読み取るために、関数read-passwdを使用できます。

Function: read-passwd prompt &optional confirm default

This function reads a password, prompting with prompt. It does not echo the password as the user types it; instead, it echoes ‘.’ for each character in the password. If you want to apply another character to hide the password, let-bind the variable read-hide-char with that character.

オプション引数confirmが非nilの場合にはパスワードを2回読み取ることで、それらが同じものであることを強制する。同じでない場合は、2回の入力が同じになるまで、ユーザーはパスワードを繰り返しタイプする必要がある。

オプション引数defaultは、ユーザーが空入力をエンターした場合のデフォルトパスワードである。defaultがnilの場合、read-passwdはnull文字列をリターンする。

20.10 ミニバッファーのコマンド

このセクションではミニバッファー内で使用するコマンドを説明します。

Command: exit-minibuffer: このコマンドはアクティブなミニバッファーをexitする。これは通常、ミニバッファー内のローカルキーマップのキーにバインドされる。

Command: self-insert-and-exit: このコマンドはキーボードでタイプされた最後の文字を挿入した後にアクティブなミニバッファーをexitする。コマンドループからの情報)を参照のこと。

Command: previous-history-element n: このコマンドは、n個前(古い)のヒストリー要素の値でミニバッファー内のコンテンツを置換する。

Command: next-history-element n: このコマンドは、n個先(新しい)のヒストリー要素の値でミニバッファー内のコンテンツを置換する。

Command: previous-matching-history-element pattern n: このコマンドはpattern(正規表現)にマッチするn個前(古い)のヒストリー要素でミニバッファー内のコンテンツを置換する。

Command: next-matching-history-element pattern n: このコマンドはpattern(正規表現)にマッチするn個先(新しい)のヒストリー要素でミニバッファー内のコンテンツを置換する。

Command: previous-complete-history-element n: このコマンドはミニバッファー内のポイントの前のカレントコンテンツを、n個前(古い)ヒストリー要素の値で置換する。

Command: next-complete-history-element n: このコマンドはミニバッファー内のポイントの前のカレントコンテンツを、n個先(新しい)ヒストリー要素の値で置換する。

20.11 ミニバッファーのウィンドウ

These functions access and select minibuffer windows, test whether they are active and control how they get resized.

Function: minibuffer-window &optional frame

This function returns the minibuffer window used for frame frame. If frame is nil, that stands for the selected frame.

Note that the minibuffer window used by a frame need not be part of that frame—a frame that has no minibuffer of its own necessarily uses some other frame’s minibuffer window. The minibuffer window of a minibuffer-less frame can be changed by setting that frame’s minibuffer frame parameter (see section バッファーのパラメーター).

Function: set-minibuffer-window window: This function specifies window as the minibuffer window to use. This affects where the minibuffer is displayed if you put text in it without invoking the usual minibuffer commands. It has no effect on the usual minibuffer input functions because they all start by choosing the minibuffer window according to the selected frame.

Function: window-minibuffer-p &optional window: この関数はwindowがミニバッファーウィンドウならnilをリターンする。windowのデフォルトは選択されたウィンドウである。

The following function returns the window showing the currently active minibuffer.

Function: active-minibuffer-window: This function returns the window of the currently active minibuffer, or nil if there is no active minibuffer.

It is not sufficient to determine whether a given window shows the currently active minibuffer by comparing it with the result of (minibuffer-window), because there can be more than one minibuffer window if there is more than one frame.

Function: minibuffer-window-active-p window: This function returns non-nil if window shows the currently active minibuffer.

The following two options control whether minibuffer windows are resized automatically and how large they can get in the process.

User Option: resize-mini-windows: This option specifies whether minibuffer windows are resized automatically. The default value is grow-only, which means that a minibuffer window by default expands automatically to accommodate the text it displays and shrinks back to one line as soon as the minibuffer gets empty. If the value is t, Emacs will always try to fit the height of a minibuffer window to the text it displays (with a minimum of one line). If the value is nil, a minibuffer window never changes size automatically. In that case the window resizing commands (see section ウィンドウのリサイズ) can be used to adjust its height.

User Option: max-mini-window-height: This option provides a maximum height for resizing minibuffer windows automatically. A floating-point number specifies a fraction of the frame’s height; an integer specifies the maximum number of lines. The default value is 0.25.

Note that the values of the above two variables take effect at display time, so let-binding them around code which produces echo-area messages will not work. If you want to prevent resizing of minibuffer windows when displaying long messages, bind the message-truncate-lines variable instead (see section エコーエリアのカスタマイズ).

20.12 ミニバッファーのコンテンツ

以下の関数はミニバッファーのプロンプトとコンテンツにアクセスします。

Function: minibuffer-prompt: この関数はカレントでアクティブなミニバッファーのプロンプト文字列をリターンする。アクティブなミニバッファーがない場合は、nilをリターンする。

Function: minibuffer-prompt-end: この関数は、ミニバッファーがカレントの場合はミニバッファープロンプトの終端のカレント位置をリターンする。それ以外はバッファーの有効な最小位置をリターンする。

Function: minibuffer-prompt-width: この関数はミニバッファーがカレントの場合は、ミニバッファープロンプトのカレントの表示幅をリターンする。それ以外は0をリターンする。

Function: minibuffer-contents: この関数はミニバッファーがカレントの場合は、ミニバッファーの編集可能なコンテンツ(つまりプロンプト以外のすべて)を文字列でリターンする。それ以外は、カレントバッファーのコンテンツ全体をリターンする。

Function: minibuffer-contents-no-properties: これはminibuffer-contentsと同様だが、テキストプロパティをコピーせず文字だけをリターンする。テキストのプロパティを参照のこと。

Command: delete-minibuffer-contents: This command erases the editable contents of the minibuffer (that is, everything except the prompt), if a minibuffer is current. Otherwise, it erases the entire current buffer.

20.13 再帰的なミニバッファー

以下の関数および変数は再帰ミニバッファーを処理します(再帰編集を参照):

Function: minibuffer-depth: この関数はアクティブなミニバッファーのカレント深さを正の整数でリターンする。アクティブなミニバッファーが存在しない場合は0をリターンする。

User Option: enable-recursive-minibuffers

If this variable is non-nil, you can invoke commands (such as find-file) that use minibuffers even while the minibuffer is active. Such invocation produces a recursive editing level for a new minibuffer. The outer-level minibuffer is invisible while you are editing the inner one.

If this variable is nil, you cannot invoke minibuffer commands when the minibuffer is active, not even if you switch to another window to do it.

コマンド名が非nilのプロパティenable-recursive-minibuffersをもつ場合は、たとえミニバッファーから呼び出された場合でも、そのコマンドは引数の読み取りにミニバッファーを使用できる。コマンドのinteractive宣言内でenable-recursive-minibuffersをtにしても、これを行うことができる(interactiveの使用を参照)。ミニバッファーコマンドnext-matching-history-element(ミニバッファー内では通常M-s)は後者を行う。

20.14 ミニバッファー、その他の事項

Function: minibufferp &optional buffer-or-name: この関数はbuffer-or-nameがミニバッファーの場合は非nilをリターンする。buffer-or-nameが省略された場合はカレントバッファーをテストする。

Variable: minibuffer-setup-hook: これはミニバッファーがエンターされたときは常に実行されるノーマルフックである。フックを参照のこと。

Macro: minibuffer-with-setup-hook function &rest body

This macro executes body after arranging for the specified function to be called via minibuffer-setup-hook. By default, function is called before the other functions in the minibuffer-setup-hook list, but if function is of the form (:append func), func will be called after the other hook functions.

The body forms should not use the minibuffer more than once. If the minibuffer is re-entered recursively, function will only be called once, for the outermost use of the minibuffer.

Variable: minibuffer-exit-hook: これはミニバッファーがexitされたときは常に実行されるノーマルフックである。

Variable: minibuffer-help-form: この変数のカレント値はミニバッファー内でhelp-formをローカルにリバインドするために使用される(ヘルプ関数を参照)。

Variable: minibuffer-scroll-window: この変数の値が非nilの場合、それはウィンドウオブジェクトである。ミニバッファー内で関数scroll-other-windowが呼び出されたときは、このウィンドウをスクロールする。

Function: minibuffer-selected-window: This function returns the window that was selected just before the minibuffer window was selected. If the selected window is not a minibuffer window, it returns nil.

Function: minibuffer-message string &rest args: This function displays string temporarily at the end of the minibuffer text, for a few seconds, or until the next input event arrives, whichever comes first. The variable minibuffer-message-timeout specifies the number of seconds to wait in the absence of input. It defaults to 2. If args is non-nil, the actual message is obtained by passing string and args through format-message. See section 文字列のフォーマット.

Command: minibuffer-inactive-mode: これはインタラクティブなミニバッファー内で使用されるメジャーモードである。キーマップminibuffer-inactive-mode-mapを使用する。ミニバッファーが別のフレームにある場合は有用かもしれない。ミニバッファーとフレームを参照のこと。

21 コマンドループ

Emacsを実行すると、ほぼ即座にエディターコマンドループ(editor command loop)にエンターします。このループはキーシーケンスを読み取り、それらの定義を実行して、結果を表示します。このチャプターでは、これらが行われる方法と、Lispプログラムがこれらを行えるようにするサブルーチンを説明します。

21.1 コマンドループの概要		コマンドループがコマンドを読み取る方法。
21.2 コマンドの定義		関数が引数を読み取る方法を指定する。
21.3 interactiveな呼び出し		引数を読み取るようにコマンドを呼び出す。
21.4 interactiveな呼び出しの区別		インタラクティブな呼び出しとコマンドを区別する。
21.5 コマンドループからの情報		検証用にコマンドループによりセットされる変数。
21.6 コマンド後のポイントの調整		コマンドの後にポイント位置を調整する。
21.7 入力イベント		入力を読み取るとき、入力がどのように見えるか。
21.8 入力の読み取り		キーボードやマウスからの入力イベントを読み取る方法。
21.9 スペシャルイベント		即座かつ個別に処理されるイベント。
21.10 時間の経過や入力の待機		ユーザー入力または経過時間の待機。
21.11 quit		`C-g`が機能する方法。quitをcatchまたは延期する方法。
21.12 プレフィクスコマンド引数		コマンドがプレフィクス引数が機能するようにセットするための方法。
21.13 再帰編集		再帰編集へのエンター、なぜ通常は再帰編集を行うべきでないのか。
21.14 コマンドの無効化		コマンドループが無効なコマンドを扱う方法。
21.15 コマンドのヒストリー		コマンドヒストリーがセットアップされる方法と、どのようにアクセスされるか。
21.16 キーボードマクロ		キーボードマクロが実装される方法。

21.1 コマンドループの概要

コマンドループが最初に行わなければならないのはキーシーケンスの読み取りです。キーシーケンスほコマンドに変換される入力イベントのシーケンスです。これは関数read-key-sequenceを呼び出すことにより行われます。Lispプログラムもこの関数を呼び出すことができます(キーシーケンス入力を参照)。これらはより低レベルのread-keyやread-event(単一イベントの読み取り)で入力を読み取ったり、discard-input(その他のイベント入力の機能を参照)で保留中の入力を無視することもできます。

キーシーケンスはカレントでアクティブなキーマップを通じてコマンドに変換されます。これが行われる方法については、See section キーの照合を参照してください。結果はキーボードマクロかインタラクティブに呼び出し可能な関数になります。キーがM-xの場合は、他のコマンドの名前を読み取り、それを呼び出します。これはコマンドexecute-extended-command(interactiveな呼び出しを参照)により行われます。

コマンドの実行に先立ち、Emacsはアンドゥ境界(undo boundary)を作成するためにundo-boundaryを実行します。アンドゥリストの保守を参照してください。

コマンドを実行するために、Emacsはまずcommand-executeを呼び出してコマンドの引数を読み取ります(interactiveな呼び出しを参照)。Lispで記述されたコマンドについては、interactive指定で引数を読み取る方法を指定します。これはプレフィクス引数(プレフィクスコマンド引数を参照)を使用したり、ミニバッファー内(ミニバッファーを参照)で確認を求めて読み取りを行うかもしれません。たとえば、コマンドfind-fileにはinteractive指定があり、これはミニバッファーを使用してファイル名を読み取ることを指定します。find-fileの関数bodyはミニバッファーを使用しないので、Lispコードから関数としてfind-fileを呼び出す場合は通常のLisp関数引数としてファイル名を文字列で与えなければなりません。

コマンドがキーボードマクロ(文字列やベクター)の場合、Emacsはexecute-kbd-macroを使用してそれを実行します(キーボードマクロを参照)。

Variable: pre-command-hook: このノーマルフックはコマンドを実行する前に、エディターコマンドループにより実行される。その際、this-command には実行しようとするコマンドが含まれ、last-commandには前のコマンドが記述される。コマンドループからの情報を参照のこと。

Variable: post-command-hook

このノーマルフックはコマンドを実行した後(quitやエラーにより早期に終了させられたコマンドを含む)に、エディターコマンドループにより実行される。その際、this-commandは正に実行されたコマンドを参照し、last-commandは前に実行されたコマンドを参照する。

このフックはEmacsが最初にコマンドループにエンターしたときにも実行される(その時点ではthis-commandとlast-commandはどちらもnil)。

pre-command-hookおよびpost-command-hookの実行中、quitは抑制されます。これらのフックのどれか1つを実行中にエラーが発生した場合、そのエラーはフックの実行を終了させません。そのかわりにエラーは黙殺され、エラーが発生した関数はそのフックから取り除かれます。

Emacsサーバー(Emacs Server in The GNU Emacs Manualを参照)に届くリクエストは、キーボードコマンドが行うのと同じように、これらの2つのフックを実行します。

21.2 コマンドの定義

スペシャルフォームinteractiveはLisp関数をコマンドに変えます。interactiveフォームは関数ボディーのトップレベルに置かなければならず、通常はボディー内の最初のフォームとして記述されます。これはラムダ式(ラムダ式を参照)とdefun(関数の定義を参照)の両方を受け入れます。このフォームは、その関数が実際に実行される間は何も行いません。このフォームの存在はフラグとしての役割りをもち、Emacsコマンドループにたいしてその関数がインタラクティブに呼び出せることを告げます。interactiveフォームの引数は、インタラクティブな呼び出しが引数を読み取る方法を指定します。

interactiveフォームのかわりに、関数シンボルのinteractive-formプロパティで指定されることもあります。このプロパティが非nil値の場合、関数ボディー内のinteractiveフォームより優先されます。この機能はほとんど使用されません。

Sometimes, a function is only intended to be called interactively, never directly from Lisp. In that case, give the function a non-nil interactive-only property, either directly or via declare (see section declareフォーム). This causes the byte compiler to warn if the command is called from Lisp. The output of describe-function will include similar information. The value of the property can be: a string, which the byte-compiler will use directly in its warning (it should end with a period, and not start with a capital, e.g., "use (system-name) instead."); t; any other symbol, which should be an alternative function to use in Lisp code.

21.2.1 `interactive`の使用

このセクションでは、Lisp関数をインタラクティブに呼び出し可能なコマンドにするinteractiveフォームの記述方法と、コマンドのinteractiveフォームの検証方法について説明します。

Special Form: interactive arg-descriptor

このスペシャルフォームは関数がコマンドであり、したがって(M-xを通じて、またはそのコマンドにバインドされたキーシーケンスのエンターすることにより)インタラクティブに呼び出されるかもしれないことを宣言する。引数arg-descriptorは、そのコマンドがインタラクティブに呼び出されたときに引数を計算する方法を宣言する。

コマンドは他の関数と同じようにLisp関数から呼び出されるかもしれないが、その場合呼び出し側は引数を提供し、arg-descriptorは効果をもたない。

interactiveフォームは関数ボディー内のトップレベルに置くか、関数シンボルのinteractive-formプロパティ((シンボルのプロパティ)を参照)になければならない。これはコマンドループが関数を呼び出す前にinteractiveフォームを調べることにより効果をもつ(interactiveな呼び出しを参照)。一度関数が呼び出されると関数ボディー内のすべてのフォームが実行される。このときボディー内にinteractiveフォームが出現しても、そのフォームは引数の評価さえされず、単にnilをリターンする。

慣例により、interactiveフォームは関数ボディー内の最初のトップレベルフォームとするべきである。interactiveフォームがシンボルのinteractive-formプロパティと関数ボディーの両方に存在する場合は、前者が優先される。interactive-formフォームは既存の関数にinteractiveフォームを追加したり、その関数を再定義することなく引数をインタラクティブに処理する方法を変更するために使用できる。

引数arg-descriptorには3つの可能性があります:

省略、またはnilの場合、コマンドは引数なしで呼び出される。コマンドが1つ以上の引数を要求する場合は、すぐにエラーとなる。
文字列の場合、その文字列の内容は改行で区切られた要素シーケンスであり、1つの要素が1つの引数に対応する¹⁰。各要素はコード文字(interactiveにたいするコード文字を参照)と、オプションでその後のプロンプト(ある文字はコード文字として使用され、コード文字としては無視されるものもある)により構成される。以下は例である:
```
(interactive "P\nbFrobnicate buffer: ")
```
コード文字‘P’はそのコマンドの1つ目の引数をrawコマンドプレフィクス(プレフィクスコマンド引数を参照)にセットする。‘bFrobnicate buffer: ’は、ユーザーに‘Frobnicate buffer:’のプロンプトを示して既存のバッファーの名前の入力を促し、これは2つ目かつ最後の引数になる。

The prompt string can use ‘%’ to include previous argument values (starting with the first argument) in the prompt. This is done using format-message (see section 文字列のフォーマット). For example, here is how you could read the name of an existing buffer followed by a new name to give to that buffer:
```
(interactive "bBuffer to rename: \nsRename buffer %s to: ")
```
文字列の先頭‘*’がある場合、そのバッファーが読み取り専用の場合にエラーがシグナルされる。

文字列の先頭が‘@’で、そのコマンドの呼び出しに使用されたキーシーケンスに何らかのマウスイベントが含まれる場合は、そのコマンドを実行する前に、それらのうち最初のイベントに結びつくウィンドウが選択される。

文字列の先頭が‘^’で、そのコマンドがシフト転換(shift-translation)を通じて呼び出された場合は、そのコマンドを実行する前に、マークをセットして一時的にリージョンをアクティブにするか、すでにアクティブなリージョンを拡張する。コマンドがシフト転換なしで呼び出されて、リージョンが一時的にアクティブな場合は、コマンドを実行する前に、そのリージョンを非アクティブにする。シフト転換はshift-select-modeにより、ユーザーレベルで制御される。Shift Selection in The GNU Emacs Manualを参照のこと。

‘*’、‘@’、^はともに使用でき、その場合は順序に意味はない。実際の引数の読み取りは残りのプロンプト文字列(‘*’、‘@’、^以外の最初の文字以降)により制御される。
文字列ではないLisp式の場合は、そのコマンドに渡す引数リストを取得するために評価されるフォームである。このフォームは通常、ユーザーから入力を読み取るためにさまざまな関数を呼び出し、それにはほとんどの場合はミニバッファー(ミニバッファーを参照)を通じてか、キーボードから直接読み取りを行う(入力の読み取りを参照)。
引数値としてポイントやマークを提供するのも一般的だが、何かを行いかつ(ミニバッファー使用の有無に関わらず)入力を読み取る場合は、読み取りの前にポイント値またはマーク値の整数を確実に取得しておくこと。カレントバッファーはサブプロセスの出力を受信するかもしれず、コマンドが入力を待つ間にサブプロセス出力が到着した場合、ポイントおよびマークの再配置が起こり得る。

以下は行ってはいけない例である:
```
(interactive
 (list (region-beginning) (region-end)
       (read-string "Foo: " nil 'my-history)))
```
これにたいし、以下はキーボード入力を読み取った後にポイントとマークを調べることにより、上記の問題を避ける例である:
```
(interactive
 (let ((string (read-string "Foo: " nil 'my-history)))
   (list (region-beginning) (region-end) string)))
```
警告: 引数値にはプリントや読み取りが不可能なデータ型を含めるべきではない。いくつかの機能は後続のセッションに読み込ませるためにcommand-historyをファイルに保存する。コマンドの引数に‘#<…>’構文を使用してプリントされるデータ型が含まれる場合、それらの機能は動作しないだろう。

しかしこれには少数の例外がある。(point)、(mark)、(region-beginning)、(region-end)などの一連の式に限定して使用するのに問題はない。なぜならEmacsはこれらを特別に認識して、コマンドヒストリー内に(値ではなく)その式を配すからである。記述した式がこれらの例外に含まれるかどうか確認するには、コマンドを実行した後に(car command-history)を調べればよい。

Function: interactive-form function: この関数はfunctionのinteractiveフォームをリターンする。functionがインタラクティブに呼び出し可能な関数(interactiveな呼び出しを参照)の場合、値はそのコマンドの引数を計算する方法を指定するinteractiveフォーム((interactive spec))である。それ以外では値はnilである。functionがシンボルの場合は、そのシンボルの関数定義が使用される。

21.2.2 `interactive`にたいするコード文字

ここで説明されているコード文字には、以下で定義されるいくつかのキーワードが含まれています:

Completion

補完を提供する。TAB、SPC、RETはcompleting-read(補完を参照)を使用して引数を読み取り、名前の補完を行う。?で利用可能な補完リストを表示する。

Existing

既存オブジェクトの名前を要求する。無効な名前は受け付けられない。カレント入力が有効でない場合、ミニバッファーをexitするコマンドはexitしない。

Default

ユーザーがテキストを何もエンターしなかった場合は、ある種のデフォルト値が使用される。デフォルトはコード文字に依存する。

No I/O

このコード文字は入力を読み取らずに引数を計算する。したがってプロンプト文字列を使用せず、与えられたプロンプト文字列は無視される。

たとえこのコード文字がプロンプト文字列を使用しなくても、これが文字列内で最後のコード文字でない場合は、その後に改行を付けなければならない。

Prompt

コード文字の直後にプロンプトが続く。プロンプトの終端は文字列の終端、または改行。

Special

このコード文字はインタラクティブ文字列の先頭にあるときのみ意味があり、プロンプトおよび改行を要求しない。単一の独立した文字である。

以下はinteractiveとともに使用されるコード文字です:

‘*’

カレントバッファーが読み取り専用の場合はエラーをシグナルする。[Special]

‘@’

このコマンドを呼び出したキーシーケンス内の最初のマウスイベントに関連するウィンドウを選択する。[Special]

‘^’

シフト転換を通じてコマンドが呼び出された場合はコマンドを実行する前に、マークをセットして一時的にリージョンをアクティブにするか、すでにリージョンがアクティブな場合はリージョンを拡張する。シフト転換を通じずにコマンドが呼び出され、リージョンが一時的にアクティブな場合は、コマンドを実行する前にそのリージョンを非アクティブにする。[Special]

‘a’

関数名(たとえばfboundpを満足するシンボル)。[Existing]、[Completion]、[Prompt]

‘b’

既存バッファーの名前。 The name of an existing buffer. デフォルトではカレントバッファー(バッファーを参照)の名前を使用する。[Existing]、[Completion]、[Default]、[Prompt]

‘B’

バッファー名。そのバッファーが存在する必要はない。デフォルトではカレントバッファーではなくもっとも最近使用されたバッファーの名前を使用する。[Completion]、[Default]、[Prompt]

‘c’

文字。カーソルはエコーエリアに移動しない。[Prompt]

‘C’

コマンド名(たとえばcommandpを満足するシンボル)。[Existing]、[Completion]、[Prompt]

‘d’

ポイント位置の整数(ポイントを参照)。[No I/O]

‘D’

A directory. The default is the current default directory of the current buffer, default-directory (see section ファイル名を展開する関数). Existing, Completion, Default, Prompt.

‘e’

そのコマンドを呼び出したキーシーケンス内の1つ目、または2つ目の非キーボードイベント。より正確には、‘e’はリストとしてイベントを取得するので、リスト内のデータを調べることができる。入力イベントを参照のこと。[No I/O]

‘e’はマウスイベント、および特別なシステムイベント(その他のシステムイベントを参照)にたいして使用する。コマンドが受け取るイベントリストは、そのイベントに依存する。入力イベントではそれぞれのイベントのリスト形式を、対応するサブセクションでそれぞれ説明しているので、参照のこと。

1つのコマンドのinteractive仕様の中で、‘e’を複数回使用できる。そのコマンドを呼び出したキーシーケンスがイベントn(リスト)をもつ場合は、‘e’のn番目がそのイベントを提供する。関数キーやASCII文字のようなリスト以外のイベントは、‘e’に関連するイベントとしてカウントされない。

‘f’

既存ファイルのファイル名(ファイルの名前を参照)。デフォルトのディレクトリーはdefault-directory。[Existing]、[Completion]、[Default]、[Prompt]

‘F’

ファイル名。ファイルが存在している必要はない。[Completion]、[Default]、[Prompt]

‘G’

ファイル名。ファイルが存在している必要はない。ユーザーがディレクトリー名だけをエンターした場合、値はそのディレクトリー名となり、そのディレクトリー名にファイル名は追加されない。[Completion]、[Default]、[Prompt]

‘i’

無関係な引数。このコード文字は引数値として常にnilを与える。[No I/O]

‘k’

キーシーケンス(キーシーケンスを参照)。これはカレントキーマップ内でコマンド(または未定義のコマンド)が見つかるまで、イベントを読み取り続ける。キーシーケンス引数は文字列、またはベクターで表される。カーソルはエコーエリアに移動しない。[Prompt]

‘k’が(マウスの)down-eventで終わるキーシーケンスを読み取った場合は、後続の(マウスの)up-eventも読み取り、それを捨てる。コード文字‘U’により、up-eventへのアクセスを得ることができる。

この種の入力は、describe-keyやglobal-set-keyのようなコマンドにより使用される。

‘K’

キーシーケンス。その定義は変更されることを意図している。これは‘k’と同じように機能するが、キーシーケンス内の最後の入力イベントにたいして、通常(必要なら)使用される未定義キーから定義済みキーへの変換を抑制する。

‘m’

マーク位置の整数。[No I/O]

‘M’

任意のテキスト。ミニバッファー内でカレントバッファーの入力メソッド(Input Methods in The GNU Emacs Manualを参照)を使用して読み取りを行い、それを文字列でリターンする。[Prompt]

‘n’

数字。ミニバッファーで読み取られる。入力が数字でない場合、ユーザーは再試行する必要がある。‘n’は決してプレフィクス引数を使用しない。[Prompt]

‘N’

数引数(numeric prefix argument)。ただしプレフィクス引数がない場合は、nのように数字を読み取る。値は常に数字。プレフィクスコマンド引数を参照のこと。[Prompt]

‘p’

数引数()これは小文字の‘p’であることに注意)。[No I/O]

‘P’

rawプレフィクス引数(これは大文字の‘P’であることに注意)。[No I/O]

‘r’

Point and the mark, as two numeric arguments, smallest first. This is the only code letter that specifies two successive arguments rather than one. This will signal an error if the mark is not set in the buffer which is current when the command is invoked. No I/O.

‘s’

任意のテキスト。ミニバッファー内で読み取りを行い文字列としてリターンする(ミニバッファーでのテキスト文字列の読み取りを参照)。C-jかRETで入力を終端する(これらの文字を入力に含めるためにC-qが使用されるかもしれない)。[Prompt]

‘S’

インターン済みのシンボル。名前はミニバッファー内で読み取られる。C-jかRETで入力を終端する。ここでは、その他の通常はシンボルを終端する文字(たとえば空白文字、丸カッコ、角カッコ)では終端されない。[Prompt]

‘U’

キーシーケンス、またはnil。‘k’(または‘K’)が読み取った後に、(もしあれば)捨てられる(マウスの)up-eventを取得するために、引数‘k’(または‘K’)の後で使用され得る。捨てられたup-eventが存在しない場合、‘U’は引数としてnilを提供する。[No I/O]

‘v’

ユーザーオプションとして宣言された変数(たとえば述語custom-variable-pを満足する)。これはread-variableを使用して変数を読み取る。Definition of read-variableを参照のこと。[Existing]、[Completion]、[Prompt]

‘x’

Lispオブジェクト。そのオブジェクトの入力構文により指定され、C-jかRETで終端される。オブジェクトは評価されない。ミニバッファーでのLispオブジェクトの読み取りを参照のこと。[Prompt]

‘X’

Lispフォームの値。‘X’は‘x’のように読み取りを行いフォームを評価して、その値がコマンドの引数になる。[Prompt]

‘z’

コーディングシステム名(シンボル)。ユーザーがnull入力をエンターした場合、引数値はnilになる。コーディングシステムを参照のこと。[Completion]、[Existing]、[Prompt]

‘Z’

コマンドにプレフィクス引数がある場合はコーディングシステム名。プレフィクス引数がない場合、‘Z’は引数値としてnilを提供する。[Completion]、[Existing]、[Prompt]

21.2.3 `interactive`の使用例

以下にinteractiveの例をいくつか挙げます:

(defun foo1 ()              ; foo1は1つの引数をとり
    (interactive)           ;   単に2単語分前に移動する。
    (forward-word 2))
     ⇒ foo1

(defun foo2 (n)             ; foo2は引数を1つとる
    (interactive "^p")      ;   引数は数引数
                            ; shift-select-modeでは、
                            ;   リージョンをアクティブにするか、拡張する
    (forward-word (* 2 n)))
     ⇒ foo2

(defun foo3 (n)             ; foo3は引数を1つとる
    (interactive "nCount:") ;   引数はミニバッファーで読み取られる
    (forward-word (* 2 n)))
     ⇒ foo3

(defun three-b (b1 b2 b3)
  "Select three existing buffers.
Put them into three windows, selecting the last one."

    (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
    (delete-other-windows)
    (split-window (selected-window) 8)
    (switch-to-buffer b1)
    (other-window 1)
    (split-window (selected-window) 8)
    (switch-to-buffer b2)
    (other-window 1)
    (switch-to-buffer b3))
     ⇒ three-b

(three-b "*scratch*" "declarations.texi" "*mail*")
     ⇒ nil

21.2.4 コマンド候補からの選択

マクロdefine-alternativesはジェネリックコマンド(generic command)を定義するために使用できます。これらはユーザーの選択により複数の候補から選択可能なinteractive関数の実装です。

Macro: define-alternatives command &rest customizations

新たなコマンドcommand(シンボル)を定義する。

最初にユーザーがM-x command RETを実行したとき、Emacsはコマンドが使用する実際のフォームにたいして確認を求め、その選択をカスタム変数として記録する。プレフィクス引数を使用すると、候補選択のプロセスを繰り返す。

変数command-alternativesには、commandの実装候補がalistで含まれる。この変数がセットされるまで、define-alternativesは効果をもたない。

customizationsが非nilの場合は、defcustomキーワード(典型的には:groupおよび:version)と、command-alternativesの宣言に追加する値により構成される候補である。

21.3 interactiveな呼び出し

コマンドループはキーシーケンスをコマンドに翻訳した後、関数command-executeを使用してその関数を呼び出します。そのコマンドが関数の場合、command-executeは引数を読み取りコマンドを呼び出すcall-interactivelyを呼び出します。自分でこれらの関数を呼び出すこともできます。

このコンテキストにおいて用語“command”はインタラクティブにコール可能な関数(または関数likeなオブジェクト)やキーボードマクロを指すことに注意してください。つまりコマンドを呼び出すキーシーケンスのことではありません(キーマップを参照)。

Function: commandp object &optional for-call-interactively

この関数はobjectがコマンドの場合はt、それ以外はnilをリターンする。

コマンドには文字列とベクター(キーボードマクロとして扱われる)、トップレベルinteractiveフォーム(interactiveの使用を参照)を含むラムダ式、そのようなラムダ式から作成されたバイトコンパイル関数オブジェクト、interactiveとして宣言(autoloadの4つ目の引数が非nil)されたautoloadオブジェクト、およびいくつかのプリミティブ関数が含まれる。interactive-formプロパティが非nilのシンボル、および関数定義がcommandpを満足するシンボルもコマンドとされる。

for-call-interactivelyが非nilの場合は、call-interactivelyが呼び出すことができるオブジェクトにたいしてのみcommandpはtをリターンする。したがってキーボードマクロは該当しなくなる。

commandpを使用する現実的な例は、ドキュメント文字列へのアクセス内のdocumentationを参照のこと。

Function: call-interactively command &optional record-flag keys

この関数はinteractive呼び出し仕様にしたがって引数を取得し、インタラクティブに呼び出し可能な関数commandを呼び出す。これはcommandがリターンするものが何であれ、それをリターンする。

たとえば、もし以下の署名をもつ関数がある場合:

(defun foo (begin end)
  (interactive "r")
  ...)

以下を行うと

(call-interactively 'foo)

これはリージョン(pointとmark)を引数としてfooを呼び出すだろう。

commandが関数でない、またはインタラクティブに呼び出せない(コマンドでない)場合は、エラーをシグナルする。たとえコマンドだとしても、キーボードマクロ(文字列かベクター)は、関数ではないので、許されないことに注意。commandがシンボルの場合、call-interactivelyはそれの関数定義を使用する。

record-flagが非nilの場合は、このコマンドとコマンドの引数は無条件にリストcommand-historyに追加される。それ以外では、引数の読み取りにミニバッファーを使用した場合のみコマンドが追加される。コマンドのヒストリーを参照のこと。

引数keysが与えられた場合、それはコマンドを呼び出すためにどのイベントを使用するかコマンドが問い合わせた場合に与えるべき、イベントシーケンスを指定するベクターである。keysがnil、または省略された場合のデフォルトは、this-command-keys-vectorのリターン値である。Definition of this-command-keys-vectorを参照のこと。

Function: funcall-interactively function &rest arguments: This function works like funcall (see section 関数の呼び出し), but it makes the call look like an interactive invocation: a call to called-interactively-p inside function will return t. If function is not a command, it is called without signaling an error.

Function: command-execute command &optional record-flag keys special

この関数はcommandを実行する。引数commandは述語commandpを満足しなければならない。つまりインタラクティブに呼び出し可能な関数かキーボードマクロでなければならない。

commandが文字列かベクターの場合は、execute-kbd-macroにより実行される。関数はrecord-flagおよびkeys引数とともにcall-interactivelyに渡される(上記参照)。

commandがシンボルの場合、その位置にシンボルの関数定義が使用される。autoload定義のあるシンボルは、インタラクティブに呼び出し可能な関数お意味するよう宣言されている場合は、コマンドとして判断される。そのような宣言は、指定されたライブラリーのロードと、シンボル定義の再チェックにより処理される。

引数specialが与えられた場合、それはプレフィクス引数を無視して、それをクリアーしないという意味である。これはスペシャルイベント(スペシャルイベントを参照)を実行する場合に使用される。

Command: execute-extended-command prefix-argument

この関数はcompleting-read(補完を参照)を使用して、ミニバッファーからコマンド名を読み取る。その後、指定されたコマンドを呼び出すためにcommand-executeを使用する。そのコマンドがリターンするのが何であれ、それがexecute-extended-commandの値となる。

そのコマンドがプレフィクス引数を求める場合は、prefix-argumentのの値を受け取る。execute-extended-commandがインタラクティブに呼び出された場合は、カレントのrawプレフィクス引数がprefix-argumentに使用され、それが何であれ実行するコマンドに渡される。

通常、execute-extended-commandはM-xの定義なので、プロンプトとして文字列‘M-x ’を使用する(execute-extended-commandを呼び出したイベントからプロンプトを受け取るほうが良いのだろうが、実装は骨が折れる)。プレフィクス引数の値の説明が、もしあれば、それもプロンプトの一部となる。

(execute-extended-command 3)
---------- Buffer: Minibuffer ----------
3 M-x forward-word RET
---------- Buffer: Minibuffer ----------
     ⇒ t

21.4 interactiveな呼び出しの区別

interactive呼び出しのときは、コマンドが(エコーエリア内の情報メッセージなどのような)視覚的な追加フィードバックを表示すべきときがあります。これを行うためには、3つの方法があります。その関数がcall-interactivelyを使用して呼び出されたかどうかテストするには、オプション引数print-messageを与えるとともに、interactive呼び出しで非nilとなるようにinteractive仕様を使うのが推奨される方法です。以下は例です:

(defun foo (&optional print-message)
  (interactive "p")
  (when print-message
    (message "foo")))

数プレフィクス引数は決してnilにならないので、わたしたちは"p"を使用します。この方法で定義された関数は、キーボードマクロから呼び出されたときにメッセージを表示します。

追加引数による上記の手法は、呼び出し側に“この呼び出しをinteractiveとして扱うように”伝えることができるので、通常は最善です。しかし、called-interactively-p.をテストすることにより、これを行うこともできます。

Function: called-interactively-p kind

この関数は、呼び出された関数がcall-interactivelyを使用して呼び出された場合はtをリターンする。

引数kindはシンボルinteractiveかシンボルanyのどちらかである。これがinteractiveの場合、called-interactively-pはユーザーから直接呼び出しが行われたとき — たとえば関数呼び出しにバインドされたキーシーケンスをユーザーがタイプした場合がそれに該当するが、ユーザーがその関数を呼び出すキーボードマクロ(キーボードマクロを参照)を実行中した場合は該当しない — だけtをリターンするkindがanyの場合、called-interactively-pはキーボードマクロを含む任意の種類のinteractive呼び出しにたいしてtをリターンする。

疑わしい場合はanyを使用すること。interactiveの使用が正しいと解っているのは、関数が実行中に役に立つメッセージを表示するかどうか判断が必要な場合だけである。

Lisp評価(またはapplyやfuncall))を通じて呼び出された、または場合、関数は決してインタラクティブに呼び出されたとは判断されない。

以下はcalled-interactively-pを使用する例である:

(defun foo ()
  (interactive)
  (when (called-interactively-p 'any)
    (message "Interactive!")
    'foo-called-interactively))

;; M-x fooとタイプする
     -| Interactive!

(foo)
     ⇒ nil

以下はcalled-interactively-pの直接呼び出しと間接呼び出しを比較した例である。

(defun bar ()
  (interactive)
  (message "%s" (list (foo) (called-interactively-p 'any))))

;; M-x barとタイプする
     -| (nil t)

21.5 コマンドループからの情報

エディターコマンドループは、自分自身と実行するコマンドのために、いくつかのLisp変数にステータス記録を保持します。this-commandおよびlast-command以外は、一般的にこれらの変数をLispプログラム内で変更するのは、良いアイデアではありません。

Variable: last-command

この変数は、コマンドループにより実行された以前のコマンド(前にカレントだったコマンド)の名前を記録する。値は通常、関数定義をもつシンボルだが、その保証はない。

コマンドがコマンドループからリターンするとき、this-commandから値がコピーされる。ただしそのコマンドが、後続のコマンドにたいしてプレフィクス引数を指定されたときを除く。

この変数は常にカレント端末にたいしてローカルであり、バッファーローカルにできない。複数の端末を参照のこと。

Variable: real-last-command: この変数はEmacsによりlast-commandと同様にセットアップされるが、Lispプログラムから決して変更されない。

Variable: last-repeatable-command: この変数は、入力イベントと一部としではなく、もっとも最近実行されたコマンドを格納する。これはコマンドrepeatが再実行を試みるコマンドである。Repeating in The GNU Emacs Manualを参照のこと。

Variable: this-command

この変数は、コマンドループにより現在実行中のコマンドの名前を記録する。last-commandと同様、通常は関数定義をもつシンボルである。

コマンドループはコマンドを実行する直前にこの変数をセットして、(そのコマンドが後続のコマンドのプレフィクス引数を指定しない場合)そのコマンドが終了したときに、その値をlast-command内にコピーする。

いくつかのコマンドは、次に実行されるコマンドが何であれ、それにたいするフラグとして、実行中の間この変数をセットする。特にテキストをkillする関数はthis-commandをkill-regionにセットするので、直後に実行された任意のkillコマンドは、killしたテキストを前にkillされたテキストに追加すべきことが解かるだろう。

特定のコマンドにおいて、エラーが発生した場合に前のコマンドとして認識されたくない場合は、これを防ぐようにそのコマンドをコーディングしなければならない。これを行う1つの方法は、以下のようにコマンドの最初でthis-commandにtをセットして、最後にthis-commandに正しい値をセットする方法である:

(defun foo (args…)
  (interactive …)
  (let ((old-this-command this-command))
    (setq this-command t)
    … 処理を行う …
    (setq this-command old-this-command)))

エラーの場合、letは古い値をリストアするので、わたしたちはletでthis-commandをバインドしない。この場合におけるletの機能は、わたしたちが避けたいと思っていることを正確に行ってしまうだろう。

Variable: this-original-command: コマンドのリマップ(コマンドのリマップを参照)が発生したときを除き、これはthis-commandと同じ値をもつ。リマップが発生した場合、this-commandは実際に実行されたコマンド、this-original-commandは実行を指定されたが他のコマンドにリマップされたコマンドを与える。

Function: this-command-keys

この関数は、現在のコマンドを呼び出したキーシーケンスと、加えてそのコマンドにたいするプレフィクス引数を生成した前のコマンドを含む文字列またはベクターをリターンする。read-eventを使用するコマンドにより、タイムアウトせずに読み取られた任意のイベントは最後に加えられる。

しかし、そのコマンドがread-key-sequenceを呼び出していた場合は、最後に読み取られたキーシーケンスをリターンする。キーシーケンス入力を参照のこと。シーケンス内のすべてのイベントが文字列として適当な文字の場合は、文字列が値になる。入力イベントを参照のこと。

(this-command-keys)
;; これを評価するためにC-u C-x C-eを使用すると、
     ⇒ "^U^X^E"

Function: this-command-keys-vector: this-command-keysと同様だが、常にベクターでイベントをリターンするので、入力イベントを文字列内に格納する複雑さを処理する必要がない(文字列内へのキーボードイベントの配置を参照)。

Function: clear-this-command-keys &optional keep-record: この関数は、this-command-keysがリターンするイベントテーブルを空にする。keep-recordがnilの場合は、その後に関数recent-keys(入力の記録)がリターンするレコードも空にする。これは特定のケースにおいて、パスワードを読み取った後、次のコマンドの一部として不用意にパスワードがエコーされるのを防ぐために有用である。

Variable: last-nonmenu-event

この変数はキーシーケンス(マウスメニューからのイベントは勘定しない)の一部として読み取られた最後の入力イベントを保持する。

この変数の1つの使い方は、x-popup-menuにたいしてどこにメニューをポップアップすべきか告げる場合である。これは内部的にy-or-n-p(Yes-or-Noによる問い合わせを参照)にも使用されている。

Variable: last-command-event

この変数には、コマンドの一部としてコマンドループに読み取られた、最後の入力イベントがセットされる。この変数は主に、self-insert-command内でどの文字が挿入されたか判断するために使用されている。

last-command-event
;; これを評価するためにC-u C-x C-eを使用すると、
     ⇒ 5

C-eのASCIIコードの5が値になる。

Variable: last-event-frame

この変数は、最後の入力イベントが送られたフレームを記録する。これは通常、そのイベントが生成されたときに選択されていたフレームだが、そのフレームの入力が他のフレームにリダイレクトされていた場合は、そのリダイレクトされていたフレームが値となる。入力のフォーカスを参照のこと。

最後のイベントがキーボードマクロ由来の場合、値はmacroになる。

21.6 コマンド後のポイントの調整

Emacs cannot display the cursor when point is in the middle of a sequence of text that has the display or composition property, or is invisible. Therefore, after a command finishes and returns to the command loop, if point is within such a sequence, the command loop normally moves point to the edge of the sequence.

変数disable-point-adjustmentをセットすることにより、コマンドはこの機能を抑制できます:

Variable: disable-point-adjustment

この変数が非nilの場合は、コマンドがコマンドループにリターンするとき、コマンドループはこれらのテキストプロパティをチェックせず、これらのプロパティをもつシーケンスの外にポイントを移動しない。

コマンドループはそれぞれのコマンドを実行する前にこの変数をnilにセットするので、あるコマンドがこれをセットしても、効果が適用されるのはそのコマンドにたいしてだけである。

Variable: global-disable-point-adjustment: この変数を非nilにセットした場合、これらのシーケンス外にポイントを移動する機能は、完全にオフになる。

21.7 入力イベント

Emacsコマンドループは入力イベント(input events)のシーケンスを読み取ります。入力イベントとは、キーボードやマウスのアクティビティ、またはEmacsに送られるシステムイベントを表します。キーボードアクティビティにたいするイベントは文字、またはシンボルです。それ以外のイベントは、常にリストになります。このセクションでは、入力イベントの表現と意味について詳細を説明します。

Function: eventp object

この関数は、objectが入力イベント、またはイベント型の場合は、非nilをリターンする。

イベント、またはイベント型として任意のシンボルが使用されるかもしれないことに注意。eventpは、あるシンボルがLispコードによりイベントとして使用されることを意図しているか否か区別できない。そのかわりに、カレントEmacsセッション内で、そのシンボルが入力として読み取られたイベント内で実際に使用されているか否かを区別する。シンボルがまだそのように使用されていない場合、eventpはnilをリターンする。

21.7.1 キーボードイベント		Ordinary characters – keys with symbols on them.
21.7.2 ファンクションキー		Function keys – keys with names, not symbols.
21.7.3 マウスイベント		マウスイベントの概観。
21.7.4 クリックイベント		マウスボタンのプッシュとリリース。
21.7.5 ドラッグイベント		ボタンをリリースする前のマウス移動。
21.7.6 ボタンダウンイベント		ボタンがプッシュされて、まだリリースされていない状態。
21.7.7 リピートイベント		ダブル、トリプルのクリック(またはドラッグ、ダウン)
21.7.8 モーションイベント		ボタンを押さずに、マウスだけを移動する。
21.7.9 フォーカスイベント		フレーム間のマウス移動。
21.7.10 その他のシステムイベント		システムが生成可能なその他のイベント。
21.7.11 イベントの例		マウスイベントの例。
21.7.12 イベントの分類		イベントシンボル内の修飾キーを見つける。イベント型。
21.7.13 マウスイベントへのアクセス		マウスイベントから情報抽出する関数。
21.7.14 スクロールバーイベントへのアクセス		スクロールバーイベントから情報取得する関数。
21.7.15 文字列内へのキーボードイベントの配置		文字列内にキーボード文字イベントを配すための特別な配慮。

21.7.1 キーボードイベント

キーボードから取得できる入力には2つの種類があります。それは通常のキーとファンクションキーです。通常のキーは文字に対応し、それらが生成するイベントはLisp内では文字で表現されます。文字イベントのイベント型は文字自身(整数)です。イベントの分類を参照してください。

入力文字イベントは0から524287までの基本コード(basic code)に加えて、以下の修飾ビット(modifier bits)の一部、またはすべてにより構成されます:

meta

文字コードのビット 2**27 はメタキーが押下された状態で文字がタイプされたことを示す。

control

文字コードのビット 2**26 は非ASCIIコントロール文字を示す。

C-aのような非ASCIIコントロール文字は、自身が特別な基本コードをもつため、それらを示すためにEmacsは特別なビットを必要としない。つまりC-aのコードは単なる1である。

しかし、%のような非ASCIIとコントロールを組み合わせてタイプした場合、取得される数値は%に 2**26 を加えた値となる(端末が非ASCIIコントロール文字をサポートすると仮定する)。

shift

文字コードのビット 2**25 はシフトキーが押下された状態でASCIIコントロール文字がタイプされたことを示す。

アルファベット文字にたいしては、基本コード自身が大文字か小文字かを示す。数字と句読点文字にたいしてシフトキーは、異なる基本コードをもつ完全に違う文字を選択する。可能な限りASCII文字として保つために、Emacsはこれらの文字にたいしてビット 2**25 を使用しない。

しかし、ASCIIはC-AとC-aを区別する方法を提供しないので、EmacsはC-Aにたいしてビット 2**25 を使用し、C-aには使用しない。

hyper

文字コードのビット 2**24 はハイパーキーが押下された状態で文字がタイプされたことを示す。

super

文字コードのビット 2**23 はスーパーキーが押下された状態で文字がタイプされたことを示す。

alt

文字コードのビット 2**22 はアルトキーが押下された状態で文字がタイプされたことを示す(ほとんどのキーボードでAltとラベルされたキーは、実際にはアルトキーではなくメタキーとして扱われる)。

プログラム内での特定のビット数値の記述は避けるのが最善の方法です。文字の修飾ビットをテストするためには、関数event-modifiers(イベントの分類を参照)を使用してください。キーバインディングを作成するときは、修飾ビットつきの文字にたいする読み取り構文を使用できます(‘\C-’、‘\M-’、...など)。define-keyでのキーバインディング作成では、文字を指定するために(control hyper ?x)のようなリストを使用できます(キーバインディングの変更を参照)。関数event-convert-listは、そのようなリストをイベント型に変換します(イベントの分類を参照)。

21.7.2 ファンクションキー

ほとんどのキーボードにはファンクションキー(function keys)があります。これは名前、または文字以外のシンボルをもつキーです。Emacs Lispではファンクションキーはシンボルとして表現されます。そのシンボル名はファンクションキーのラベルの小文字です。たとえばF1とラベルされたキーを押下すると、シンボルf1で表される入力イベントが生成されます。

ファンクションキーのイベント型は、イベントシンボルそれ自身です。イベントの分類を参照してください。

ファンクションキーにたいするシンボルネーミングの慣習には、以下のような特別なケースがいくつかあります:

backspace、tab、newline、return、delete

これらのキーは、ほとんどのキーボードにおいて特別にキーをもつ、一般的なASCIIコントロール文字に対応する。

ASCIIではC-iとTABは同じ文字である。端末がこれらを区別できる場合、Emacsは前者を整数の9、後者をシンボルtabで表現することにより、Lispプログラムにこれらの違いを伝える。

ほとんどの場合、これら2つを区別するのは役に立たない。そのためlocal-function-key-map(イベントシーケンス変換のためのキーマップを参照)はtabを9にマップするようセットアップされている。したがって文字コード9(文字C-i)へのキーバインディングはtabにも適用される。このグループ内の他のシンボルも同様である。関数read-charが、これらのイベントを文字に変換する場合も同様である。

ASCIIでは、BSは実際はC-hである。しかしbackspaceは文字コード8(BS)ではなく、文字コード127(DEL)に変換される。ほとんどのユーザーにとって、これは好ましいだろう。

left、up、right、down

矢印カーソルキー

kp-add、kp-decimal、kp-divide、…

キーパッドキー(標準的なキーボードにおいては右側にある)。

kp-0、kp-1、…

キーパッド数字キー。

kp-f1、kp-f2、kp-f3、kp-f4

キーパッドPFキー。

kp-home、kp-left、kp-up、kp-right、kp-down

キーパッド矢印キー。Emacsは通常これらを非キーパッドのキーhome、left、…に変換する。

kp-prior、kp-next、kp-end、kp-begin、kp-insert、kp-delete

通常は他の箇所にあるキーと重複するキーパッド追加キー。Emacsは通常これらを同じような名前の非キーパッドキーに変換する。

ファンクションキーにたいしても修飾キーALT、CTRL、HYPER、META、SHIFT、SUPERを使用できます。シンボル名のプレフィクスとしてこれらを表します:

‘A-’: アルト修飾。
‘C-’: コントロール修飾。
‘H-’: ハイパー修飾。
‘M-’: メタ修飾。
‘S-’: シフト修飾。
‘s-’: スーパー修飾。

したがって、METAを押下した場合のF3キーにたいするシンボルはM-f3になります。複雑のプレフィクスを使用する場合は、アルファベット順に記述することを推奨します。とはいえ、キーバインディングが修飾されたファンクションキーを探す際、引数の順序は関係ありません。

21.7.3 マウスイベント

Emacsは4つの種類のマウスイベントをサポートします。それはクリックイベント、ドラッグイベント、ボタンダウンイベント、モーションイベントです。すべてのマウスイベントはリストで表現されます。このリストのCARはイベント型です。イベント型はどのマウスボタンが関与するのか、それにたいしてどの修飾キーが使用されたかを示します。イベント型によりダブル、あるいはトリプルでボタンが押されたかを区別することもできます(リピートイベントを参照)。残りのリスト要素は、位置と時間の情報を提供します。

キーの照合においては、イベント型だけが問題になります。2つのイベントが同じコマンドを実行するためには、同じイベント型が必要です。実行されるコマンドはinteractiveのコード‘e’を使用して、これらのイベントの完全な値にアクセスできます。interactiveにたいするコード文字を参照してください。

マウスイベントで開始されたキーシーケンスはカレントバッファーではなく、マウスのあったウィンドウ内のバッファーのキーマップを使用して読み取られます。これはウィンドウ内でクリックすることによりそのウィンドウやそのウィンドウのバッファーが選択されることを意味しません。つまり、それは完全にそのキーシーケンスのコマンドバインディングの制御下にあるのです。

21.7.4 クリックイベント

ユーザーが同じ場所でマウスボタンを押してからリリース(release: 離す)すると、clickイベントが生成されます。すべてのマウスクリックイベントは同じフォーマットを共有します:

(event-type position click-count)

event-type

これはマウスボタンが使用されたことを示す。これはシンボルmouse-1、mouse-2、…のうちのどれかで、マウスボタンは左から右に番号が付される。

ファンクションキーにたいして行うのと同様にアルト、コントロール、ハイパー、メタ、シフト、スーパーの修飾にたいしてプレフィクス‘A-’、‘C-’、‘H-’、‘M-’、‘S-’、‘s-’も使用できる。

このシンボルは、イベントのイベント型の役割りももつ。イベントのキーバインディングはこれらの型により示される。したがって、mouse-1にたいするキーバインディングが存在する場合、そのバインディングはevent-typeがmouse-1であるようなすべてのイベントに適用されるだろう。

position

これはマウスクリックがどこで発生したかを表すマウス位置リスト(mouse position list)である。詳細は以下を参照のこと。

click-count

これは同じマウスボタンを素早く繰り返し押下したときの回数である。リピートイベントを参照のこと。

クリックイベントのpositionスロット内にあるマウス位置リストの内容にアクセスするためには、一般的にはマウスイベントへのアクセスにドキュメントされている関数を使用するべきです。このリストの明示的なフォーマットは、どこでクリックが発生したかに依存します。テキストエリア、モードライン、ヘッダーライン、フリンジ、マージンエリアでのクリックにたいして、マウス位置リストは以下のフォーマットをもちます

(window pos-or-area (x . y) timestamp
 object text-pos (col . row)
 image (dx . dy) (width . height))

以下はこれらのリスト要素がもつ意味です:

window

クリックが発生したウィンドウ。

pos-or-area

テキストエリア内でクリックされた文字のバッファー位置。またはテキストエリア外がクリックされた場合は、クリックが発生したウィンドウエリア。これはシンボルmode-line、header-line、vertical-line、left-margin、right-margin、left-fringe、right-fringeのどれか。

特別な場合の1つとして、pos-or-areaが単なるシンボルではなく、(上記シンボルのいずれか1つの)シンボルを含むリストの場合がある。これはEmacsにより登録されたイベントにたいする、イマジナリープレフィクスキー(imaginary prefix key)の後に発生する。キーシーケンス入力を参照のこと。

x, y

クリックの相対ピクセル座標(relative pixel coordinates)。あるウィンドウのテキストエリア内でのクリックにたいする座標原点(0 . 0)は、テキストエリアの左上隅となる。ウィンドウのサイズを参照のこと。モードラインまたはヘッダーライン内でのクリックにたいする座標原点は、そのウィンドウ自身の左上隅となる。フリンジ、マージン、垂直ボーダー(vertical border)では、xな有意なデータをもたない。フリンジ、マージンでは、yはヘッダーラインの最下端からの相対位置である。すべてのケースにおいてxおよびy座標は右方向および下方向で増加する。

timestamp

そのイベントが発生した時刻を、システム依存の初期時刻(initial time)からの経過ミリ秒で表す整数。

object

クリック位置に文字列タイプのテキストプロパティが存在しない場合はnil、存在する場合は(string . string-pos)形式のコンスセル:

string: クリックされた文字列。すべてのテキストプロパティを含む。
string-pos: クリックが発生した文字列内の位置。

text-pos

For clicks on a marginal area or on a fringe, this is the buffer position of the first visible character in the corresponding line in the window. For clicks on the mode line or the header line, this is nil. For other events, it is the buffer position closest to the click.

col, row

これらはx、yの位置にあるグリフ(gliph)の、実際の行と列の座標数値である。行xがその行の実際のテキストの最後の列を超える場合、colはデフォルトの文字幅をもつ仮想的な追加列数を加えた値が報告される。そのウィンドウがヘッダーラインをもつ場合、行0はヘッダーラインとなり、ヘッダーラインをもたない場合はテキストエリアの上端ラインが行0となる。ウィンドウのテキストエリアのクリックにたいしては、テキストエリアの左端列が列0となり、モードラインまたはヘッダーラインのクリックにたいしてはそのラインの左端が列0となる。フリンジまたは垂直ボーダーのクリックにたいしては、これらは有意なデータをもたない。マージンのクリックにたいしては、colはマージンエリアの左端、rowはマージンエリアの上端から測られる。

image

これはクリックが発生した場所のイメージオブジェクトである。クリックされた場所にイメージが存在しない場合はnil、イメージがクリックされた場合はfind-imageによりリターンされるイメージオブジェクトである。

dx, dy

これらはobjectの左上隅(0 . 0)からの相対的ピクセル座標である。objectがnilの場合は、クリックされた文字グリフの左上隅からの相対座標である。

width, height

これらはobjectのピクセル幅とピクセル高さであり、objectがnilの場合はクリックされた文字グリフのピクセル幅とピクセル高さである。

スクロールバーへのクリックにたいして、positionは以下の形式をもちます:

(window area (portion . whole) timestamp part)

window: スクロールバーがクリックされたウィンドウ。
area: これはシンボルvertical-scroll-barである。
portion: スクロールバーの上端からクリック位置までのピクセル数。GTK+を含むいくつかのツールキットでは、Emacsがこれらのデータを抽出できないので、値は常に0となる。
whole: スクロールバーの全長のピクセル数。GTK+を含むいくつかのツールキットでは、Emacsがこれらのデータを抽出できないので、値は常に0となる。
timestamp: イベントが発生したミリ秒時刻。GTK+を含むいくつかのツールキットでは、Emacsがこれらのデータを抽出できないので、値は常に0となる。
part: クリックが発生したスクロールバー部分。これはシンボルhandle(スクロールバーのハンドル)、above-handle(ハンドルの上側エリア)、below-handle(ハンドルの下側エリア)、up(スクロールバー端の上矢印)、down(スクロールバー端の下矢印)のいずれかである。

21.7.5 ドラッグイベント

Emacsでは、特別なことをしなくてもドラッグイベントを取得できます。ドラッグイベント(drag event)は、ユーザーがマウスボタンを押下して、ボタンをリリースする前に、マウスを異なる文字位置に移動すると毎回発生します。すべてのマウスイベントと同じように、ドラッグイベントはLispではリストで表現されます。このリストは以下のように、開始マウス位置と最終位置ぼ両方を記録します:

(event-type
 (window1 START-POSITION)
 (window2 END-POSITION))

ドラッグイベントにたいしては、シンボルevent-typeの名前に、プレフィクス‘drag-’が含まれます。たとえば、ボタン2を押下したままマウスをドラッグすると、drag-mouse-2イベントが生成されます。このイベントの2つ目と3つ目の要素は、マウス位置リスト(クリックイベントを参照)としてドラッグの開始と終了の位置を与えます。任意のマウスイベントの2つ目の要素には、同じ方法でアクセスできます。しかし、ドラッグイベントは最初に選択されていたフレームの境界外で終了するかもしれません。この場合、3つ目の要素の位置リストに、ウィンドウのかわりにそのフレームが含まれます。

‘drag-’プレフィクスは、その後に‘C-’や‘M-’のような修飾キープレフィクスが続きます。

read-key-sequenceがキーバインディングをもたず、対応するクリックイベントにキーバインディングがあるようなドラッグイベントを受け取った場合、この関数はそのドラッグイベントをドラッグ開始位置でのクリックイベントに変更します。これは、もし望まなければクリックイベントとドラッグイベントを区別する必要がないことを意味します。

21.7.6 ボタンダウンイベント

クリックイベントとドラッグイベントは、ユーザーがマウスボタンをリリースしたときに発生します。ボタンがリリースされるまでクリックとドラッグを区別することはできないので、リリース前にイベントが発生することはありません。

ボタンが押下されたらすぐに何か処理したい場合は、ボタンダウン(button-down)イベントを処理する必要があります¹¹。これらはevent-typeのシンボル名に‘down-’が含まれることを除き、クリックイベントとまったく同じようなリストにより表現されます。‘down-’プレフィクスの後には、‘C-’や‘M-’のような修飾キープレフィクスが続きます。

関数read-key-sequenceは、コマンドバインディングをもたないボタンダウンイベントを無視します。したがって、Emacsコマンドループもこれらを無視します。これは、ボタンダウンイベントで何かしたい場合以外は、ボタンダウンイベントの定義について心配する必要がないことを意味します。ボタンダウンイベントを定義する通常の理由は、ボタンがリリースされるまで(モーションイベントを読み取ることにより)マウスモーションを追跡できるからです。モーションイベントを参照してください。

21.7.7 リピートイベント

マウスを移動せずに同じマウスボタンを素早く2回以上連続して押下すると、Emacsは2回目とそれ以降の押下にたいして、特別なリピート(repeat)マウスイベントを生成します。

もっとも一般的なリピートイベントは、ダブルクリック(double-click)イベントです。Emacsはボタンを2回クリックしたときに、ダブルクリックイベントを生成します。このイベントは、(すべてのクリックイベントが通常そうであるように)ボタンをリリースしたときに発生します。

ダブルクリックイベントのイベント型には、プレフィクス‘double-’が含まれます。したがって、metaを押しながら2つ目のマウスボタンをダブルクリックすると、LispプログラムにはM-double-mouse-2が渡されます。ダブルクリックイベントがバインディングをもたない場合、対応する通常のクリックイベントのバインディングが実行に使用されます。したがって、実際に望んでいなければダブルクリック機能に注意を払う必要はありません。

ユーザーがダブルクリックを行うとき、Emacsはまず通常のクリックイベントを生成し、その後ダブルクリックイベントを生成します。したがって、ダブルクリックイベントのコマンドバインディングは、すでにシングルクリックイベントが実行された想定でデザインしなければなりません。つまりシングルクリックの結果から開始して、ダブルクリックの望むべき結果を生成しなければならないのです。

This is convenient, if the meaning of a double click somehow builds on the meaning of a single click—which is recommended user interface design practice for double clicks.

ボタンをクリックした後もう一度ボタンを押下して、そのままマウス一般的を開始した場合、最終的にボタンをリリースしたときダブルドラッグ(double-drag)イベントが取得されます。このイベント型には単なる‘drag’のかわりに‘double-drag’が含まれます。ダブルドラッグイベントがバインディングをもたない場合、それがあたかも通常のドラッグイベントだったかのようにEmacsはかわりのバインディングを探します。

ダブルクリックまたはダブルドラッグイベントの前に、Emacsはユーザーが2回目にボタンを押したタイミングでダブルダウン(double-down)イベントを生成します。このイベント型には、単なる‘down’のかわりに‘double-down’が含まれます。ダブルダウンイベントがバインディングをもたない場合、それがあたかも通常のボタンダウンイベントだったかのようにEmacsはかわりのバインディングを探します。どちらの方法でもバインディングが見つからなかった場合、ダブルダウンイベントは無視されます。

要約すると、ボタンをクリックしてすぐにまた押したとき、Emacsは1回目のクリックにたいしてダウンイベントとクリックイベントを生成し、2回目に再度ボタンを押したときにダブルダウンイベント、そして最後にダブルクリックまたはダブルドラッグイベントを生成します。

ボタンを2回クリックした後もう一度押したとき、それらすべてが素早く連続で行われた場合、Emacsはトリプルダウン(triple-down)イベントと、その後続のトリプルクリック(triple-click)またはトリプルドラッグ(triple-drag)イベントを生成します。これらイベントのイベント型には、‘double’のかわりに‘triple’が含まれます。トリプルイベントがバインディングをもたない場合、Emacsは対応するダブルイベントに使用されるであろうバインディングを使用します。

ボタンを3回以上クリックした後、再度ボタンを押した場合、3回を超える押下にたいするイベントはすべてトリプルイベントになります。Emacsはクワドループル(quadruple: 4連)、クインティプル(quintuple: 5連)、...等のイベントにたいして個別のイベント型をもちません。しかし、ボタンが何回押下されたかを正確に見つけるために、イベントリストを調べることができます。

Function: event-click-count event: この関数はeventを誘因した連続したボタン押下の回数をリターンする。eventがダブルダウン、ダブルクリック、ダブルドラッグの場合、値は2である。eventがトリプルイベントの場合、値は3以上になる。eventが(リピートイベントではない)通常のマウスイベントの場合、値は1である。

User Option: double-click-fuzz

リピートイベントを生成するためには、ほぼ同じスクリーン位置で連続でマウスボタンを押下しなければならない。double-click-fuzzの値は、ダブルクリックを生成するために連続する2回のクリック間で、マウスが移動(水平および垂直)するかもしれない最大ピクセル数を指定する。

この変数はドラッグとみなされるマウスモーションの閾値でもある。

User Option: double-click-time: リピートイベントを生成するためには、連続するボタン押下のミリ秒間隔が、double-click-timeの値より小さくなければならない。double-click-timeをnilにセットすると、複数回クリック検知が完全に無効になる。tにセットすると、時間制限が取り除かれる。その場合、Emacsは位置だけで複数回クリックを検知する。

21.7.8 モーションイベント

Emacsは、ボタンアクティビティが何もないマウスのモーション(motion: 動き)を記述するマウスモーション(mouse motion)イベントを生成するときがあります。マウスモーションイベントは、以下のようなリストにより表現されます:

(mouse-movement POSITION)

positionは、マウスカーソルのカレント位置を指定するマウス位置リスト(see section クリックイベント)です。ドラッグイベントの終了位置のように、この位置リストは最初に選択されていた境界外の位置を表すかもしれず、その場合はそのフレーム内のその位置のウィンドウが含まれる。

スペシャルフォームtrack-mouseは、ボタン内でのモーションイベントの生成を有効にします。track-mouseフォームの外側では、Emacsはマウスの単なるモーションにたいするイベントは生成せず、これらのイベントは発生しません。マウスの追跡を参照してください。

21.7.9 フォーカスイベント

Window systems provide general ways for the user to control which window gets keyboard input. This choice of window is called the focus. When the user does something to switch between Emacs frames, that generates a focus event. The normal definition of a focus event, in the global keymap, is to select a new frame within Emacs, as the user would expect. See section 入力のフォーカス, which also describes hooks related to focus events.

フォーカスイベントは、以下のようにLispのリストで表現されます:

(switch-frame new-frame)

ここでnew-frameは切り替え先のフレームです。

Xウィンドウマネージャーには、あるウィンドウにマウスを移動するだけで、そこにフォーカスされるようにセットアップするものがいくつかあります。通常は、他の種類の入力が到着するまで、Lispプログラムがフォーカスの変更を知る必要はありません。Emacsはユーザーが新たなフレーム内で実際にキーボードのキーをタイプするかマウスボタンを押下したときしか、フォーカスイベントを生成しません。つまりフレーム間でマウスを移動させても、フォーカスイベントは生成されません。

キーシーケンスの途中におけるフォーカスイベントは、そのシーケンスを誤ったものにするかもしれません。そのため、Emacsは決してキーシーケンスの途中でフォーカスイベントを生成しません。ユーザーがキーシーケンスの途中(つまりプレフィクス引数の後)でフォーカスを変更した場合、複数イベントキーシーケンスの前か後にフォーカスイベントが到着するように、Emacsはフォーカスイベントを記録しておきます。

21.7.10 その他のシステムイベント

他にもシステム内での出来事を表現するイベント型が少数あります。

(delete-frame (frame))

このイベントの種類は、ユーザーがウィンドウマネージャーに特定のウィンドウを削除するコマンドを与えたことを示し、Emacsのフレームにたいして発生する。

フレーム削除(delete-frame)イベントの標準的な定義は、frameを削除する。

(iconify-frame (frame))

このイベントの種類は、ウィンドウマネージャーを使用してユーザーがframeをアイコン化したことを示す。標準的な定義はignoreである。これは、そのフレームがすでにアイコン化されているので、Emacsが行う必要のことは何もないからである。このイベント型の目的は、望むならこのようなイベントの追跡を可能にしておくためである。

(make-frame-visible (frame))

このイベントの種類は、ウィンドウマネージャーを使用してユーザーがframeを非アイコン化したことを示す。標準的な定義はignoreである。これは、そのフレームがすでに可視化されているので、Emacsが行う必要のことは何もないからである。

(wheel-up position)

(wheel-down position)

この種類のイベントは、マウスホイールを移動したことにより発生する。position要素は、そのイベント発生時のマウスカーソル位置を指定するマウス位置リスト(クリックイベントを参照)である。

This kind of event is generated only on some kinds of systems. On some systems, mouse-4 and mouse-5 are used instead. For portable code, use the variables mouse-wheel-up-event and mouse-wheel-down-event defined in mwheel.el to determine what event types to expect for the mouse wheel.

(drag-n-drop position files)

この種類のイベントは、Emacs外部アプリケーション内でファイルグループが選択され、それがEmacsフレーム内にドラッグアンドドロップされたときに発生する。

要素positionは、そのイベント位置を記述しマウスクリックイベントで使用されるフォーマット(クリックイベントを参照)と同じである。要素filesはドラッグアンドドロップされたファイル名のリストである。通常は、それらのファイルをvisitすることにより、このイベントは処理される。

この種類のイベントは、現在のところある種のシステムでのみ生成される。

help-echo

この種類のイベントは、テキストプロパティhelp-echoをもつバッファーテキスト部分上にマウスポインターが移動したときに生成される。生成されるイベントは以下の形式をもつ:

(help-echo frame help window object pos)

イベントパラメーターの正確な意味と、ヘルプテキストを表示するためにこれらのパラメーターを使用する方法は、Text help-echoで説明されているか

sigusr1

sigusr2

これらのイベントは、EmacsプロセスがシグナルSIGUSR1およびSIGUSR2を受け取ったときに生成される。シグナルは追加情報を運搬しないので、追加データは含まれない。これらのシグナルはデバッグに有用である(エラーによるデバッガへのエンターを参照)。

ユーザーシグナルをcatchするためには、special-event-map(アクティブなキーマップを参照)内で対応するイベントにバインドする。そのコマンドは引数なしで呼び出され、last-input-event内の特定のシグナルイベントが利用できる。たとえば:

(defun sigusr-handler ()
  (interactive)
  (message "Caught signal %S" last-input-event))

(define-key special-event-map [sigusr1] 'sigusr-handler)

シグナルハンドラーをテストするために、自身でEmacsにシグナルを送信できる:

(signal-process (emacs-pid) 'sigusr1)

language-change

この種類のイベントは、MS-Windows上で入力言語が変更されたときに生成される。これは通常、キーボードキーが異なる言語の文字でEmacsに送られることを意味する。生成されるイベントは、以下の形式をもつ:

(language-change frame codepage language-id)

ここでframeは言語が変更されたときカレントだったフレームであり、codepageは新たなコードページ番号(codepage number)、language-idは新たな入力言語の数値IDである。codepageに対応するコーディングシステム(コーディングシステムを参照)は、cpcodepageまたはwindows-codepageである。language-idを文字列に変更する(たとえばset-language-environmentのようなさまざまな言語依存機能にたいしこれを使用する)には、以下のようにw32-get-locale-info関数を使用する:

;; 英語にたいする"ENU"のような言語の省略形を取得する
(w32-get-locale-info language-id)
;; "English (United States)"のような
;; その言語の完全な英語名を取得する
(w32-get-locale-info language-id 4097)
;; その言語の完全なローカライズ名を取得する
(w32-get-locale-info language-id t)

キーシーケンスの途中、つまりプレフィクスキーの後にこれらのイベントの1つが到着した場合、複数イベントキー内ではなくその前または後にそのイベントが到着するように、Emacsはそのイベントを記録する。

21.7.11 イベントの例

ユーザーが同じ場所でマウス左ボタンを押して離した場合、それは以下のようなイベントシーケンスを生成します:

(down-mouse-1 (#<window 18 on NEWS> 2613 (0 . 38) -864320))
(mouse-1      (#<window 18 on NEWS> 2613 (0 . 38) -864180))

コントロールキーを押したままユーザーがマウス第2ボタンを押してマウスをある行から次の行へドラッグした場合、以下のような2つのイベントが生成されます:

(C-down-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219))
(C-drag-mouse-2 (#<window 18 on NEWS> 3440 (0 . 27) -731219)
                (#<window 18 on NEWS> 3510 (0 . 28) -729648))

メタキーとシフトキーを押したままユーザーがそのウィンドウのモードライン上でマウス第2ボタンを押して他ウィンドウへマウスをドラッグした場合、以下のようなイベントのペアーが生成されます:

(M-S-down-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844))
(M-S-drag-mouse-2 (#<window 18 on NEWS> mode-line (33 . 31) -457844)
                  (#<window 20 on carlton-sanskrit.tex> 161 (33 . 3)
                   -453816))

The frame with input focus might not take up the entire screen, and the user might move the mouse outside the scope of the frame. Inside the track-mouse special form, that produces an event like this:

(mouse-movement (#<frame *ielm* 0x102849a30> nil (563 . 205) 532301936))

SIGUSR1シグナルを処理するためにはインタラクティブ関数を定義して、それをsignal usr1イベントシーケンスにバインドします:

(defun usr1-handler ()
  (interactive)
  (message "Got USR1 signal"))
(global-set-key [signal usr1] 'usr1-handler)

21.7.12 イベントの分類

すべてのイベントはイベント型(event type)をもちます。イベント型はキーバインディング目的でイベントをクラス分けします。キーボードイベントにたいするイベント型はイベント値と等しく、したがって文字のイベント型は文字、ファンクションキーシンボルのイベント型はそのシンボル自身です。リストであるようなイベントのイベント型は、そのリストのCAR内のシンボルです。したがって、イベント型は常にシンボルか文字です。

同じ型の２つのイベントはキーバインディングに関する限り同じです。したがって、それらは常に同じコマンドを実行します。これらが同じことを行う必要があるという意味ではありませんが、イベント全体を調べてから何を行うか決定するコマンドもいくつかあります。、たとえば、バッファー内でどこに作用するか決定するためにマウスイベントの場所を使用するコマンドもいくつかあります。

広範なイベントのクラス分けが役に立つときもあります。たとえば、他の修飾キーやマウスボタンが使用されたかとは無関係に、METAキーとともに呼び出されたイベントを尋ねたいと思うかもしれません。

関数event-modifiersはevent-basic-typeは、そのような情報を手軽に取得するために提供されています。

Function: event-modifiers event

この関数は、eventがもつ修飾子のリストをリターンする。この修飾子はシンボルでありshift、control、meta、alt、hyper、superが含まれる。さらにマウスイベントシンボルの修飾子リストには常にclick、drag、downのいずれか1つが含まれる。ダブルイベントまたはトリプルイベントにはdoubleまたはtripleも含まれる。

引数eventはイベントオブジェクト全体、または単なるイベント型かもしれない。eventがカレントEmacsセッション内で入力として読み取られたイベント内で決して使用されないシンボルの場合は、実際にeventが変更されたときでも、event-modifiersはnilをリターンできる。

いくつか例を挙げる:

(event-modifiers ?a)
     ⇒ nil
(event-modifiers ?A)
     ⇒ (shift)
(event-modifiers ?\C-a)
     ⇒ (control)
(event-modifiers ?\C-%)
     ⇒ (control)
(event-modifiers ?\C-\S-a)
     ⇒ (control shift)
(event-modifiers 'f5)
     ⇒ nil
(event-modifiers 's-f5)
     ⇒ (super)
(event-modifiers 'M-S-f5)
     ⇒ (meta shift)
(event-modifiers 'mouse-1)
     ⇒ (click)
(event-modifiers 'down-mouse-1)
     ⇒ (down)

クリックイベントにたいする修飾リストは明示的にclickを含むが、イベントシンボル名自身は‘click’を含まない。

Function: event-basic-type event

この関数はeventを記述するキー、またはマウスボタンをリターンする。event引数はevent-modifiersの場合と同様。たとえば:

(event-basic-type ?a)
     ⇒ 97
(event-basic-type ?A)
     ⇒ 97
(event-basic-type ?\C-a)
     ⇒ 97
(event-basic-type ?\C-\S-a)
     ⇒ 97
(event-basic-type 'f5)
     ⇒ f5
(event-basic-type 's-f5)
     ⇒ f5
(event-basic-type 'M-S-f5)
     ⇒ f5
(event-basic-type 'down-mouse-1)
     ⇒ mouse-1

Function: mouse-movement-p object: This function returns non-nil if object is a mouse movement event. See section モーションイベント.

Function: event-convert-list list

この関数は修飾子名リストと基本イベント型(basic event type)を、それらすべてを指定するイベント型に変換する。基本イベント型はそのリストの最後の要素でなければならない。たとえば、

(event-convert-list '(control ?a))
     ⇒ 1
(event-convert-list '(control meta ?a))
     ⇒ -134217727
(event-convert-list '(control super f1))
     ⇒ C-s-f1

21.7.13 マウスイベントへのアクセス

このセクションではマウスボタンやモーションイベント内のデータアクセスに役に立つ関数を説明します。同じ関数を使用してキーボードイベントデータにもアクセスできますが、キーボードイベントに不適切なデータ要素は0またはnilになります。

以下の2つの関数は、マウスイベントの位置を指定するマウス位置リスト(see section クリックイベント)をリターンします。

Function: event-start event

これはeventの開始位置をリターンする。

eventがクリックイベントまたはボタンダウンイベントの場合、この関数はそのイベントの位置をリターンする。eventがドラッグイベントの場合は、そのドラッグの開始位置をリターンする。

Function: event-end event

これはeventの終了位置をリターンする。

eventがドラッグイベントの場合、この関数はユーザーがマウスボタンをリリースした位置をリターンする。eventがクリックイベントまたはボタンダウンイベントの場合、値はそのイベント固有の開始位置となる。

Function: posnp object: この関数はobjectが(クリックイベントに記述されたいずれかのフォーマットの)マウス位置リストの場合は非nil、それ以外ではnilをリターンする。

以下の関数は、引数にマウス位置リストをとり、そのリストのさまざまな部分をリターンします:

Function: posn-window position: positionがあったウィンドウをリターンする。positionが最初イベントがあったフレーム外の位置を表す場合は、かわりにそのフレームをリターンする。

Function: posn-area position: position内に記録されたウィンドウエリアをリターンする。そのウィンドウのテキストエリアでイベントが発生したときはnil、それ以外ではイベントがどこで発生したかを識別するシンボルをリターンする。

Function: posn-point position: position内のバッファー位置をリターンする。ウィンドウのテキストエリア、マージンエリア、フリンジでイベントが発生したときは、バッファー位置を識別する整数値、それ以外では値は未定義である。

Function: posn-x-y position

position内のピクセル単位のxy座標を、コンスセル(x . y)でリターンする。これらはposn-windowにより与えられるウィンドウにたいする相対座標である。

以下は、あるウィンドウのテキストエリア内のウィンドウ相対座標をフレーム相対座標に変換する方法を示す例である:

(defun frame-relative-coordinates (position)
  "POSITIONのフレーム相対座標をリターンする。
POSITIONはウィンドウのテキストエリアにあるものとする。"
  (let* ((x-y (posn-x-y position))
         (window (posn-window position))
         (edges (window-inside-pixel-edges window)))
    (cons (+ (car x-y) (car edges))
          (+ (cdr x-y) (cadr edges)))))

Function: posn-col-row position

この関数は、position内のバッファー位置にたいして推定される列と行を含むコンスセル(col . row)をリターンする。リターン値は、positionにたいするxとyの値より計算され、そのフレームのデフォルト文字幅とデフォルト行高(行間スペースを含む)の単位で与えられる(そのため、実際の文字サイズが非デフォルト値の場合には、実際の行と列は、これらの計算された値とは異なるかもしれない)。

rowは、そのテキストエリアの上端から数えられることに注意すること。positionにより与えられるウィンドウがヘッダーライン(see section ウィンドウのヘッダーライン)をもつ場合、そのヘッダーラインはrowの数に含まない。

Function: posn-actual-col-row position

position内の実際の行と列を、コンスセル(col . row)でリターンする。値はposition与えられるウィンドウの実際の行と列である。クリックイベントを参照のこと。positionが実際のポジション値を含まない場合、この関数はnilをリターンする。この場合、おおよその値を取得するためにposn-col-rowを使用できる。

この関数は、タブ文字やイメージによるビジュアル列数のように、ディスプレイ上の文字のビジュアル幅を意味しない。標準的な文字単位の座標が必要ｎ場合は、かわりにposn-col-rowを使用すること。

Function: posn-string position: position内の文字列オブジェクトををnil、またはコンスセル(string . string-pos)でリターンする。

Function: posn-image position: position内のイメージオブジェクトをnil、または(image ...)でリターンする。

Function: posn-object position: position内のイメージオブジェクト、または文字列オブジェクトをnil、イメージ(image ...)、またはコンスセル(string . string-pos)でリターンする。

Function: posn-object-x-y position: position内のオブジェクトの左上隅からのピクセル単位のxy座標を、コンスセル(dx . dy)でリターンする。positionがバッファーテキストの場合は、その位置にもっとも近いバッファーテキストの相対位置をリターンする。

Function: posn-object-width-height position: position内のオブジェクトのピクセル幅とピクセル高さを、コンスセル(width . height)でリターンする。positionがバッファー位置の場合は、その位置の文字のサイズをリターンする。

Function: posn-timestamp position: position内のタイムスタンプをリターンする。これはミリ秒で表されたイベント発生時刻である。

以下の関数は与えられた特定のバッファー、またはスクリーン位置により与えられる位置リストを計算します。上述の関数で、この位置リスト内のデータにアクセスできます。

Function: posn-at-point &optional pos window

この関数は位置pos in windowにたいする位置リストをリターンする。posのデフォルトはwindow内のポイントであり、windowのデフォルトは選択されたウィンドウである。

window内でposが不可視の場合、posn-at-pointはnilをリターンする。

Function: posn-at-x-y x y &optional frame-or-window whole: この関数は、指定されたフレームまたはウィンドウframe-or-window(デフォルトは選択されたウィンドウ)内のピクセル座標xとyに対応する位置情報をリターンする。xとyは、使用されたフレームまたはウィンドウにたいする相対座標である。wholeがnilの場合、座標はウィンドウのテキストエリアにたいする相対座標であり、それ以外ではスクロールバー、マージン、フリンジを含むウィンドウエリア全体にたいする相対座標である。

21.7.14 スクロールバーイベントへのアクセス

以下の関数は、スクロールバーイベントの解析に役立ちます。

Function: scroll-bar-event-ratio event: この関数はスクロールバーで発生したスクロールバーイベントの位置の垂直位置割り合いをリターンする。値は位置の割り合いを表す2つの整数を含むコンスセル(portion . whole)である。

Function: scroll-bar-scale ratio total

この関数は、(実質的には)ratioにtotalを乗じて、結果を整数に丸める。引数ratioは数字ではなく、scroll-bar-event-ratioによりリターンされる典型的な値ペアー(num . denom)である。

この関数はスクロールバー位置をバッファー位置にスケーリングするのに便利である。以下のようにこれを行う:

(+ (point-min)
   (scroll-bar-scale
      (posn-x-y (event-start event))
      (- (point-max) (point-min))))

スクロールバーイベントは、xy座標ペアーのかわりに割り合いを構成する2つの整数をもつことを思い出してほしい。

21.7.15 文字列内へのキーボードイベントの配置

文字列が使用される場所のほとんどにおいて、わたしたちはテキスト文字を含むもの、つまりバッファーやファイル内で見出すのと同種のものとして、文字列を概念化します。Lispプログラムはときおり、キーボード文字、たとえばキーシーケンスやキーボードマクロ定義かもしれないキーボード文字を概念的に含む文字列を使用します。しかし文字列内へのキーボード文字の格納は、歴史的な互換性の理由により複雑な問題であり、常に可能なわけではありません。

新たに記述するプログラムでは文字列内にキーボードイベントを格納しないことにより、これらの複雑さを扱うことを避けるよう推奨します。以下はこれを行う方法です:

lookup-keyおよびdefine-keyの引数として使用するのでなければ、キーシーケンスにたいして文字列のかわりにベクターを使用する。たとえば、read-key-sequenceのかわりにread-key-sequence-vector、this-command-keysのかわりにthis-command-keys-vectorを使用できる。
メタ文字を含むキーシーケンス定数を記述する際は、たとえそれを直接define-keyに渡す場合でもベクターを使用する。
文字列かもしれないキーシーケンスの内容を調べる必要があるときは、それをリストに変換するために最初にlistify-key-sequence(その他のイベント入力の機能を参照)を使用する。

複雑さはキーボード入力に含まれるかもしれない修飾ビットに起因します。メタ修飾以外の修飾ビットは文字列に含めることができず、メタ文字も特別な場合だけ許されます。

GNU Emacsの初期のバージョンでは、メタ文字を128から255のコードで表していました。その頃は基本文字コードの範囲は0から127だったので、すべてのキーボード文字を文字列内に適合させることができました。Lispプログラムの多くは、特にdefine-keyやその種の関数の引数として文字列定数内にメタ文字を意味する‘\M-’を使用し、キーシーケンスとイベントシーケンスは常に文字列として表現されていました。

127を超えるより大きい基本文字コードと追加の修飾ビットにたいするサポートを加えたとき、わたしたちはメタ文字の表現を変更する必要がありました。現在では文字のメタ修飾を表すフラグは 2**27 であり、そのような値は文字列内に含めることができません。

プログラムで文字列定数内の‘\M-’をサポートするために、文字列内に特定のメタ文字を含めるための特別なルールがあります。以下は入力文字シーケンスとして文字列を解釈するためのルールです:

キーボード文字の値の範囲が0から127の場合は、文字列を変更せずに含めることができる。
これらの文字のコード 2**27 から 2**27+127, までの範囲のメタ修飾された変種も文字列に含めることができるが、それらの数値を変更しなければならない。値が128から255の範囲となるように、ビット 2**7 のかわりにビット 2**27 をセットしなければならない。ユニバイト文字列だけがこれらの文字を含むことができる。
265を超える非ASCII文字はマルチバイト文字に含めることができる。
その他のキーボード文字イベントは文字列に適合させられない。これには128から255の範囲のキーボードイベントが含まれる。

キーボード入力文字の文字列定数を構築するread-key-sequenceのような関数は、イベントが文字列内に適合しないときは文字列のかわりにベクターを構築するというルールにしたがいます。

文字列内で入力構文‘\M-’を使用すると、それは128から255の範囲のコード、つまり対応するキーボードイベントを文字列内に配すために変更するとき取得されるのと同じコードが生成されます。したがって文字列内のメタイベントは、それが文字列内にどのように配置されたかと無関係に一貫して機能します。

しかし、ほとんどのプログラムはこのセクションの冒頭の推奨にしたがって、これらの問題を避けるほうがよいでしょう。

21.8 入力の読み取り

エディターコマンドループはキーシーケンスの読み取りに関数read-key-sequenceを使用し、この関数はread-eventを使用します。イベント入力にたいしてこれらの関数、およびその他の関数がLisp関数から利用できます。一時的な表示のmomentary-string-display、および時間の経過や入力の待機のsit-forも参照してください。端末の入力モードの制御、および端末入力のデバッグに関する関数と変数については、端末の入力を参照してください。

高レベル入力機能についてはミニバッファーを参照してください。

21.8.1 キーシーケンス入力		キーシーケンスを読み取る方法。
21.8.2 単一イベントの読み取り		イベントを1つだけ読み取る方法。
21.8.3 入力イベントの変更と変換		Emacsが読み取られたイベントを変更する方法。
21.8.4 入力メソッドの呼び出し		入力メソッドを使用するイベントを読み取る方法。
21.8.5 クォートされた文字の入力		文字の指定をユーザーに問い合わせる。
21.8.6 その他のイベント入力の機能		入力イベントの最読み取りや破棄の方法。

21.8.1 キーシーケンス入力

コマンドループはread-key-sequenceを呼び出すことにより、キーシーケンスの入力を一度に読み取ります。Lisp関数もこの関数を呼び出すことができます。たとえばdescribe-keyはキーを説明するためにこの関数を使用します。

Function: read-key-sequence prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop

この関数はキーシーケンスを読み取り、それを文字列またはベクターでリターンする。この関数は完全なキーシーケンスに蓄積されるまで、つまりカレントでアクティブなキーマップを使用してプレフィクスなしでコマンドを指定するのに十分なキーシーケンスとなるまでイベントの読み取りを継続する(マウスイベントで始まるキーシーケンスは、カレントバッファーではなくマウスのあったウィンドウ内のバッファーのキーマップを使用して読み取られることを思い出してほしい)。

イベントがすべて文字で、それらがすべて文字列に適合する場合、read-key-sequenceは文字列をリターンする(文字列内へのキーボードイベントの配置を参照)。それ以外の場合は文字、シンボル、リストなどすべての種類のイベントを保持できるベクターをリターンする。文字列またはベクターの要素は、キーシーケンス内のイベントである。

キーシーケンスのo読み取りには、そのイベントを変換するさまざまな方法が含まれる。イベントシーケンス変換のためのキーマップを参照のこと。

引数promptはプロンプトとしてエコーエリアに表示される文字列か、プロンプトを表示しないnilである。引数continue-echoが非nilの場合、それは前のキーの継続としてそのキーをエコーすることを意味する。

通常、元となる大文字のイベントが未定義で、それと等価な小文字イベントが定義されている場合、大文字のイベントは小文字のイベントに変換される。引数dont-downcase-lastが非nilの場合、それは最後のイベントを小文字に変換しないことを意味する。これはキーシーケンスを定義するときに適している。

引数switch-frame-okが非nilの場合は、たとえ何かをタイプする前にユーザーがフレームを切り替えたとしても、この関数がswitch-frameを処理すべきでないことを意味する。キーシーケンスの途中でユーザーがフレームを切り替えた場合、またはシーケンスの最初だがswitch-frame-okがnilのときにフレームを切り替えた場合、そのイベントはカレントキーシーケンスの後に延期される。

引数command-loopが非nilの場合は、そのキーシーケンスがコマンドを逐次読み取る何かによりa読み取られることを意味する。呼び出し側が1つのキーシーケンスだけを読み取る場合は、nilを指定すべきである。

以下の例では、Emacsはエコーエリアにプロンプト‘?’を表示して、その後ユーザーがC-x C-fをタイプしている。

(read-key-sequence "?")

---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------

     ⇒ "^X^F"

関数read-key-sequenceはquitを抑制する。この関数による読み取りの間にタイプされたC-gは他の文字と同じように機能し、quit-flagをaセットしない。quitを参照のこと。

Function: read-key-sequence-vector prompt &optional continue-echo dont-downcase-last switch-frame-ok command-loop: これはread-key-sequenceと同様だが、キーシーケンスを常にベクターでリターンし、文字列では決してリターンしない点が異なる。文字列内へのキーボードイベントの配置を参照のこと。

入力文字が大文字(またはシフト修飾をもつ)で、キーバインディングをもたないが、等価な小文字はキーバインディングをもつ場合、read-key-sequenceはその文字を小文字に変換します。lookup-keyはこの方法による大文字小文字変換を行わないことに注意してください。

入力を読み取った結果がシフト変換(shift-translation)されていたような場合、Emacsは変数this-command-keys-shift-translatedに非nil値をセットします。シフト変換されたキーにより呼びだされたときは挙動を変更する必要があるLispプログラムは、この変数を調べることができます。たとえば、関数handle-shift-selectionはリージョンをアクティブ、または非アクティブにするか判断するためにこの変数の値を調べます(handle-shift-selectionを参照)。

この関数read-key-sequenceも、マウスイベントのいくつかを変換します。これはバインドされていないドラッグイベントをクリックイベントに変換し、バインドされていないボタンダウンイベントを完全に破棄します。さらにフォーカスイベントとさまざまなウィンドウイベントの再配置も行うため、これらのイベントはキーシーケンス中に他のイベントとともに決して出現しません。

When mouse events occur in special parts of a window, such as a mode line or a scroll bar, the event type shows nothing special—it is the same symbol that would normally represent that combination of mouse button and modifier keys. The information about the window part is kept elsewhere in the event—in the coordinates. But read-key-sequence translates this information into imaginary prefix keys, all of which are symbols: header-line, horizontal-scroll-bar, menu-bar, mode-line, vertical-line, and vertical-scroll-bar. You can define meanings for mouse clicks in special window parts by defining key sequences using these imaginary prefix keys.

たとえば、read-key-sequenceを呼び出した後にそのウィンドウのモードラインをマウスでクリックすると、以下のように2つのマウスイベントが取得されます:

(read-key-sequence "Click on the mode line: ")
     ⇒ [mode-line
         (mouse-1
          (#<window 6 on NEWS> mode-line
           (40 . 63) 5959987))]

Variable: num-input-keys: この変数の値は、そのEmacsセッション内で処理されたキーシーケンスの数である。これには端末からのキーシーケンスと、実行されるキーボードマクロにより読み取られたキーシーケンスが含まれる。

21.8.2 単一イベントの読み取り

read-event,read-char、read-char-exclusiveは、コマンド入力にたいするもっとも低レベルの関数です。

Function: read-event &optional prompt inherit-input-method seconds

この関数はコマンド入力の次のイベントを読み取り、リターンする。必要ならイベントが利用可能になるまで待機する。

リターンされるイベントはユーザーから直接のイベントかもしれないし、またはキーボードマクロからのイベントかもしれない。イベントはキーボードの入力コーディングシステム(端末I/Oのエンコーディングを参照)により復号されない。

オプション引数promptが非nilの場合、それはエコーエリアにプロンプトとして表示される文字列である。nilの場合、read-eventは入力待ちを示すメッセージを何も表示せず、エコーを行うことによりプロンプトの代用とする。エコーで表示されるのはカレントコマンドに至ったイベントや読み取られたイベントの説明である。エコーエリアを参照のこと。

inherit-input-methodが非nilの場合、(もしあれば)非ASCII文字の入力を可能にするためにカレントの入力メソッドが採用される。それ以外では、このイベントの読み取りにたいして入力メソッドの処理が無効になる。

cursor-in-echo-areaが非nilの場合、read-eventはカーソルを一時的にエコーエリアの、そこに表示されているメッセージの終端に移動する。それ以外では、read-eventはカーソルを移動しない。

secondsが非nilの場合、それは入力を待つ最大秒数を指定する数値である。その時間内に入力が何も到着しない場合、read-eventは待機を終えてnilをリターンする。浮動小数点数secondsは待機する秒の分数を意味する。いくつかのシステムではサポートされるのは整数の秒数だけであり、そのようなシステムではsecondsは切り捨てられる。secondsがnilの場合、read-eventは入力が到着するのに必要なだけ待機する。

secondsがnilの場合、ユーザー入力が到着するのを待つ間、Emacsはアイドル状態にあるとみなされる。この期間中にアイドルタイマー — run-with-idle-timer(アイドルタイマーを参照) — を実行できる。しかしsecondsが非nilの場合には、非アイドル状態は変更されずに残る。read-eventが呼び出されたときEmacsが非アイドルだった場合、read-eventの処理を通じて非アイドルのままとなる。Emacsがアイドルだった場合(これはアイドルタイマー内部からその呼び出しが行われた場合に起こり得る)は、アイドルのままとまる。

read-eventがヘルプ文字として定義されたイベントを取得した場合、ある状況においてはread-eventがリターンせずに直接イベントを処理することがある。ヘルプ関数を参照のこと。その他のスペシャルイベント(special events)(スペシャルイベントを参照)と呼ばれる特定のイベントもread-eventで直接処理される。

以下はread-eventを呼び出してから右矢印キーを押下したとき何が起こるかの例である:

(read-event)
     ⇒ right

Function: read-char &optional prompt inherit-input-method seconds

この関数はコマンド入力の文字を読み取り、それをリターンする。ユーザーが文字以外(たとえばマウスクリックやファンクションキー)のイベントを生成した場合、read-charはエラーをシグナルする。引数はread-eventと同じように機能する。

1つ目の例では、ユーザーは文字1(ASCIIコード49)をタイプしている。2つ目の例では、eval-expressionを使用してミニバッファーからread-charを呼び出すキーボード定義を示している。read-charは、キーボードマクロの直後の文字1を読み取る。その後、eval-expressionはリターン値をエコーエリアに表示する。

(read-char)
     ⇒ 49

;; M-:を使用して以下を評価するものとする
(symbol-function 'foo)
     ⇒ "^[:(read-char)^M1"

(execute-kbd-macro 'foo)
     -| 49
     ⇒ nil

Function: read-char-exclusive &optional prompt inherit-input-method seconds: この関数はコマンド入力の文字を読み取り、それをリターンする。ユーザーが文字以外のイベントを生成した場合、read-char-exclusiveはそれを無視して文字を取得するまで他のイベントを読み取る。引数はread-eventと同じように機能する。

上記でquitを抑制する関数はありません。

Variable: num-nonmacro-input-events: この変数は端末から受信した入力イベント(キーボードマクロにより生成されたイベントは勘定されない)の総数を保持する。

read-key-sequenceと異なり、関数read-event、read-char、read-char-exclusiveはイベントシーケンス変換のためのキーマップで説明した変換を行わないことを強調しておきます。単一キー読み取りでこれらの変換を行いたい場合は、関数read-keyを使用してください。

Function: read-key &optional prompt

This function reads a single key. It is intermediate between read-key-sequence and read-event. Unlike the former, it reads a single key, not a key sequence. Unlike the latter, it does not return a raw event, but decodes and translates the user input according to input-decode-map, local-function-key-map, and key-translation-map (see section イベントシーケンス変換のためのキーマップ).

引数promptはプロンプトとしてエコーエリアに表示する文字列で、nilはプロンプトを表示しないことを意味する。

Function: read-char-choice prompt chars &optional inhibit-quit: この関数は1つの文字を読み取りリターンするためにread-keyを使用する。これはchars(許容される文字のリスト)のメンバー以外の入力を無視する。オプションで、有効な入力を待つ間のquitイベントも無視する。read-char-choice呼び出しの間にhelp-form(ヘルプ関数を参照)を非nil値にバインドした場合、help-charの押下によりhelp-formが評価され結果が表示される。その後、有効な入力文字、またはキーボードquitの待機を継続する。

Function: read-multiple-choice prompt choices

Ask user a multiple choice question. prompt should be a string that will be displayed as the prompt.

choices is an alist where the first element in each entry is a character to be entered, the second element is a short name for the entry to be displayed while prompting (if there’s room, it might be shortened), and the third, optional entry is a longer explanation that will be displayed in a help buffer if the user requests more help.

The return value is the matching value from choices.

(read-multiple-choice
 "Continue connecting?"
 '((?a "always" "Accept certificate for this and future sessions.")
   (?s "session only" "Accept certificate this session only.")
   (?n "no" "Refuse to use certificate, close connection.")))

The read-multiple-choice-face face is used to highlight the matching characters in the name string on graphical terminals.

21.8.3 入力イベントの変更と変換

Emacsはextra-keyboard-modifiersに合わせて読み取ったすべてのイベントを変更して、read-eventからリターンする前に、(もし適切なら)keyboard-translate-tableを通じてそれを変換します。

Variable: extra-keyboard-modifiers

この変数は、Lispプログラムにキーボード上の修飾キーを“押下”させる。値は文字である。文字の修飾子だけが対象となる。ユーザーがキーボードのキーを押下するたびに、その修飾キーがすでに押下されたかのように処理される。たとえば、extra-keyboard-modifiersを?\C-\M-aにバインドした場合、このバインディングのスコープ内にある間、すべてのキーボード入力文字はコントロール修飾とメタ修飾を適用されるだろう。文字?\C-@は0と等価なので、この目的にたいしてはコントロール文字として勘定されないが、修飾無しの文字として扱われる。したがってextra-keyboard-modifiersを0にセットすることにより、すべての修飾をキャンセルできる。

When using a window system, the program can press any of the modifier keys in this way. Otherwise, only the CTL and META keys can be virtually pressed.

この変数は実際にキーボード由来のイベントだけに適用され、マウスイベントやその他のイベントには効果がないことに注意されたい。

Variable: keyboard-translate-table

この端末ローカルな変数はキーボード文字にたいする変換テーブルである。これによりコマンドバインディングを変更することなく、キーボード上のキーを再配置できる。値は通常、文字テーブル、またはnilある(文字列かベクターも指定できるが、時代遅れとされている)

keyboard-translate-tableが文字テーブル(文字テーブルを参照)の場合、キーボードから読み取られたそれぞれの文字はその文字テーブルを調べる。非nilの値が見つかった場合は、実際の入力文字のかわりにそれを使用する。

この変換は文字が端末から読み取られた後、最初に発生することに注意されたい。recent-keysのような記録保持機能や文字を記録するdribbleファイルは、この変換の後に処理される。

さらに、この変換は入力メソッド(入力メソッドを参照)に文字を提供する前に行われることにも注意されたい。入力メソッド処理の後に文字を変換したい場合は、translation-table-for-input(文字の変換を参照)を使用すること。

Function: keyboard-translate from to: この関数は文字コードfromを文字コードtoに変換するために、keyboard-translate-tableを変更する。必要な場合は、キーボード変換テーブルを作成する。

以下はC-xでカット、C-でコピー、C-vでペーストを処理するようにkeyboard-translate-tableを使用する例です:

(keyboard-translate ?\C-x 'control-x)
(keyboard-translate ?\C-c 'control-c)
(keyboard-translate ?\C-v 'control-v)
(global-set-key [control-x] 'kill-region)
(global-set-key [control-c] 'kill-ring-save)
(global-set-key [control-v] 'yank)

拡張ASCII入力をサポートするグラフィカルな端末上では、シフトキーとともにタイプすることにより、標準的なEmacsにおける意味をこれらの文字から依然として取得することが可能です。これはキーボード変換が関与する文字とは異なりますが、それらは通常と同じ意味をもちます。

read-key-sequenceのレベルでイベントシーケンスを変換するメカニズムについては、イベントシーケンス変換のためのキーマップを参照してください。

21.8.4 入力メソッドの呼び出し

イベント読み取り関数は、もしあればカレント入力メソッドを呼び出します(入力メソッドを参照)。input-method-functionの値が非nilの場合、関数を指定します。read-eventが修飾ビットのないプリント文字(SPCを含む)を読み取ったときは、その文字を引数としてその関数を呼び出します。

Variable: input-method-function

これが非nilの場合、その値はカレントの入力メソッド関数を指定する。

警告: この変数はletでバインドしてはならない。この変数はしばしばバッファーローカルであり、入力の前後(これは正にあなたがバインドするであろうタイミングである)でバインドした場合、Emacsが待機中に非同期にバッファーを切り替えると誤ったバッファーに値がリストアされるだろう。

入力メソッド関数は、入力として使用されるイベントのリストをリターンするべきです(このリストがnilの場合、それは入力がないことを意味するので、read-event他のイベントを待機する)。これらのイベントはunread-command-events(その他のイベント入力の機能を参照)内のイベントの前に処理されます。入力メソッドによりリターンされるイベントは、たとえそれらが修飾ビットのないプリント文字であっても、再度入力メソッドに渡されることはありません。

入力メソッド関数がread-eventまたはread-key-sequenceを呼び出した場合は、再帰を防ぐために最初にinput-method-functionをnilにバインドするべきです。

キーシーケンスの2つ目および後続のイベントを読み取るときは、入力メソッド関数は呼び出されません。したがって、それらの文字は入力メソッドの処理対象ではありません。入力メソッド関数はoverriding-local-mapとoverriding-terminal-local-mapの値をテストするべきです。これらの変数のいずれかが非nilの場合、入力メソッドは引数をリストにputして、それ以上の処理を行わずにそのリストをリターンするべきです。

21.8.5 クォートされた文字の入力

ユーザーが手軽にコントロール文字やメタ文字。リテラルや8進文字コードを指定できるように、文字の指定をもとめることができます。コマンドquoted-insertこの関数を使用します。

Function: read-quoted-char &optional prompt

この関数はread-char同様だが、最初に読み取った文字が8進数 (0–7)の場合は任意の個数の8進数(8進数以外の文字を見つけた時点でストップする)を読み取り、その文字コードにより表される文字をリターンする。8進シーケンスを終端させた文字がRETの場合、それは無視される。他の終端文字は、この関数がリターンした後に入力として使用される。

最初の文字の読み取り時はquitは抑制されるので、ユーザーははC-gを入力できる。quitを参照のこと。

promptが与えられた場合、それはユーザーへのプロンプトに使用する文字列を指定する。プロンプト文字列は、その後の1つの‘-’とともに常にエコーエリアに表示される。

以下の例では、ユーザーは8進数の177(10進数の127)をタイプしている。

(read-quoted-char "What character")

---------- Echo Area ----------
What character 1 7 7-
---------- Echo Area ----------

     ⇒ 127

21.8.6 その他のイベント入力の機能

This section describes how to peek ahead at events without using them up, how to check for pending input, and how to discard pending input. See also the function read-passwd (see section パスワードの読み取り).

Variable: unread-command-events

この変数はコマンド入力として読み取り待機中のイベントのリストを保持する。イベントはこのリスト内の出現順に使用され、使用されるごとにリストから取り除かれる。

ある関数がイベントを読み取ってそれを使用するかどうか決定する場合がいくつかあるので、この変数が必要になる。この変数にイベントを格納すると、コマンドループおよにコマンド入力を読み取る関数により、イベントは通常のように処理される。

たとえば、数引数を実装する関数は、任意の個数の数字を読み取る。数字イベントが見つからないとき、関数はそのイベントを読み戻す(unread)ので、そのイベントはコマンドループにより通常通り読み取られることができる。同様に、インクリメンタル検索は、検索において特別な意味をもたないイベントを読み戻すために、この機能を使用する。なぜなら、それらのイベントは検索をexitして、通常どおり実行されるべきだからである。

unread-command-eventsにイベントを置くためにキーシーケンスからイベントを抽出するには、listify-key-sequence(以下参照)を使用するのが簡単で信頼のおける方法である。

もっとも最近読み戻したイベントが最初に再読み取りされるように、このリストの先頭にイベントを追加するのが通常である。

通常このリストから読み取ったイベントは、そのイベントが最初に読み取られたときにすでに一度追加されたときのように、カレントコマンドのキーシーケンスに(たとえばthis-command-keysにリターンされたとみのように)追加される。フォーム(t . event)の要素は、カレントコマンドのキーシーケンスにeventを強制的に追加する。

Function: listify-key-sequence key: この関数は文字列またはベクターのkeyを、unread-command-events置くことができる個別のイベントのリストに変換する。

Function: input-pending-p &optional check-timers

この関数は、コマンド入力がカレントで読み取り可能かどうか判断する。入力が利用可能なら即座にtを、それ以外はnilをリターンする。非常に稀だが、入力が利用できないときにt

オプション引数check-timersが非nilの場合、Emacsは順部位ができたら任意のタイマーを実行する。遅延実行のためのタイマーを参照のこと。

Variable: last-input-event

この変数は最後に読み取られた端末入力イベントがコマンドの一部なのか、それともLispプログラムによる明示的なものなのかを記録する。

以下の例では、文字1(ASCIIコード49)をLispプログラムが読み取っている。C-e(C-x C-eは式を評価するコマンドとする)がlast-command-eventに値として残っている間は、それがlast-input-eventの値となる。

(progn (print (read-char))
       (print last-command-event)
       last-input-event)
     -| 49
     -| 5
     ⇒ 49

Macro: while-no-input body…

この構成はbodyフォームを実行して、入力が何も到着しない場合だけ最後のフォームの値をリターンする。bodyフォームを実行する間に何らかの入力が到着した場合は、それらの入力をする(quitのように機能する)。while-no-inputフォームは実際のquitによりabortした場合はnil、入力の到着によりabortした場合はtをリターンする。

bodyの一部でinhibit-quitを非nilにバインドした場合、その部分の間に到着した入力は、その部分が終わるまでabortしない。

両方のabort条件をbodyにより計算されたすべての可能な値で区別できるようにしたい場合は、以下のようにコードを記述する:

(while-no-input
  (list
    (progn . body)))

Variable: while-no-input-ignore-events: This variable allow setting which special events while-no-input should ignore. It is a list of symbols.

Function: discard-input

この関数は端末入力バッファーの内容を破棄して定義処理中かもしれないキーボードマクロをキャンセルする。この関数はnilをリターンする。

以下の例では、フォームの評価開始直後にユーザーが数字か文字をタイプするかもしれない。sleep-forがスリープを終えた後、discard-inputはスリープ中にタイプされた文字を破棄する。

(progn (sleep-for 2)
       (discard-input))
     ⇒ nil

21.9 スペシャルイベント

特定のスペシャルイベント(special event)は、読み取られると即座に非常に低レベルで処理されます。read-event関数はそれらのイベントを自身で処理して、それらを決してリターンしません。かわりに、スペシャルイベント以外の最初のイベントを待ち、それをリターンします。

スペシャルイベントはエコーされず、決してキーシーケンスにグループ化されず、last-command-eventや(this-command-keys)の値として出現することもありません。スペシャルイベントは数引数を破棄し、unread-command-eventsによる読み戻しができず、キーボードマクロ内に出現することもないでしょうし、キーボードマクロ定義中にキーボードマクロに記録されることもありません。

しかし、スペシャルイベントは読み取られた直後にlast-input-event内に出現するので、これがイベント定義にたいして実際のイベントを探す方法になります。

イベント型iconify-frame、make-frame-visible、delete-frame、drag-n-drop、language-change、およびsigusr1ようなユーザーシグナルは通常この方法により処理されます。何がスペシャルイベントで、スペシャルイベントをどのように処理するかを定義するキーマップは、変数special-event-map(アクティブなキーマップを参照)の中にあります。

21.10 時間の経過や入力の待機

待機関数(wait function)は特定の時間が経過するか、入力があるまで待機するようにデザインされています。たとえば、計算の途中でユーザーがディスプレイを閲覧できるように一時停止したいときがあるかもしれません。sit-forは一時停止して画面を更新、sleep-forは画面を更新せずに一時停止して、入力が到着したら即座にリターンします。

Function: sit-for seconds &optional nodisp

この関数は、(ユーザーからの保留中入力がない場合は)再描画を行ってから、seconds秒、または入力が利用可能になるまで待機する。sit-forの通常の目的は、ディスプレイしたテキストをユーザーが読み取る時間を与えるためである。入力が何も到着せず(その他のイベント入力の機能を参照)、時間をフルに待機した場合はt、それ以外はnilが値となる。

引数secondsは整数である必要はない。浮動小数点数の場合、sit-forは秒の少数点数を待機する。整数の秒だけをサポートするいくつかのシステムでは、secondsは切り捨てられる。

保留中の入力が存在しない場合、式(sit-for 0)は遅延なしに再描画をリクエストする(redisplay)と等価である。強制的な再表示を参照のこと。

nodispが非nilの場合sit-forは再描画を行わないが、それでも入力が利用可能になると(またはタイムアウト時間が経過すると)即座にリターンする。

バッチモード(batchモードを参照)では、たとえ標準入力ディスクリプタからの入力でも割り込みできまい。これは以下で説明するsleep-forでも同じである。

(sit-for seconds millisec nodisp)のように、3つの引数でsit-forを呼び出すことも可能だが時代遅れだと考えられている。

Function: sleep-for seconds &optional millisec

この関数は表示を更新せず、単にseconds秒間一時停止する。これは利用可能な入力に注意を払わない。この関数はnilをリターンする。

引数secondsは整数である必要はない。浮動小数点数の場合、sleep-forは秒の少数点数を待機する。整数の秒だけをサポートするいくつかのシステムでは、secondsは切り捨てられる。

オプション引数millisecはミリ秒単位で追加の待機期間を指定する。これはsecondsで指定された期間に追加される。システムが小数点の秒数をサポートしない場合、非0のmillisecを指定するとエラーとなる。

遅延を保証したい場合はsleep-forを使用する。

現在時刻を取得する関数については、時刻を参照してください。

21.11 quit

Lisp関数を実行中にC-gをタイプすると、Emacsが何を行っていてもEmacsをquit(中止、終了)させます。これはアクティブなコマンドループの再内に制御がリターンすることを意味します。

コマンドループがキーボード入力待機中にC-gをタイプしてもquitはしません。これは通常の入力文字として機能します。もっともシンプルなケースでは、通常C-gはquitの効果をもつkeyboard-quitを実行するので、区別できませんしかしプレフィクスキーの後のC-gは、未定義のキー組み合わせになります。これはプレフィクスキーやプレフィクスキーも同様にキャンセルする効果をもちます。

ミニバッファー内では、C-gは異なる定義をもち、それはミニバッファーをabort(失敗、中止、中断)します。これは実際にはミニバッファーをexitしてquitします(単にquitするのはミニバッファー内のコマンドループにリターンするだろう)。C-gがなぜコマンドリーダーが入力読み取り時に直接quitしないかという理由は、ミニバッファー内でC-gの意味をこの方法により再定義可能にするためです。プレフィクスキーの後のC-gはミニバッファー内で再定義されておらず、プレフィクスキーおよびプレフィクス引数のキャンセルという通常の効果をもちます。もしC-gｇヴぁ常に直接quitするなら、これは不可能でしょう。

C-gが直接quitを行うときは、変数quit-flagをtにセットすることによりそれを行います。Emacsは適切なときにこの変数をチェックして、nilでない場合はquitします。どのような方法でも、quit-flagを非nilにセットするとquitが発生します。

Cコードのレベルでは、どこでもquitを発生させることはできず、quit-flagをチェックする特別な場所でのみquitが発生します。この理由は、他の場所でquitすると、Emacsの内部状態が矛盾が生じるかもしれないからです。安全な場所までquitが遅延されるので、quitがEmacsをクラッシュさせることがなくなります。

read-key-sequenceやread-quoted-charのような特定の関数は、たとえ入力を待機中でもquitを抑制します。quitするかわりに、C-gは要求された入力として処理されます。read-key-sequenceの場合、これはコマンドループ内でのC-gの特別な振る舞いを引き起こすのに役立ちます。read-quoted-charの場合、これはC-gをクォートするのにC-qを使用できるようにします。

You can prevent quitting for a portion of a Lisp function by binding the variable inhibit-quit to a non-nil value. Then, although C-g still sets quit-flag to t as usual, the usual result of this—a quit—is prevented. Eventually, inhibit-quit will become nil again, such as when its binding is unwound at the end of a let form. At that time, if quit-flag is still non-nil, the requested quit happens immediately. This behavior is ideal when you wish to make sure that quitting does not happen within a critical section of the program.

(read-quoted-charのような)いくつかの関数では、quitを起こさない特別な方法でC-gが処理されます。これはinhibit-quitをtにバインドして入力を読み取り、再びinhibit-quitがnilになる前にquit-flagをnilにセットすることにより行われます。以下は、これを行う方法を示すためのread-quoted-charの抜粋です。この例は入力の最初の文字の後で通常のquitを許す方法も示しています。

(defun read-quoted-char (&optional prompt)
  "…documentation…"
  (let ((message-log-max nil) done (first t) (code 0) char)
    (while (not done)
      (let ((inhibit-quit first)
            …)
        (and prompt (message "%s-" prompt))
        (setq char (read-event))
        (if inhibit-quit (setq quit-flag nil)))
      … 変数codeをセット …)
    code))

Variable: quit-flag: この変数が非nilでinhibit-quitがnilの場合、macsは即座にquitする。C-gをタイプすると、通常はinhibit-quitとは無関係にquit-flagを非nilにセットする。

Variable: inhibit-quit: この変数は、quit-flagが非nilにセットされているときEmacsがquitするかどうかを決定する。inhibit-quitが非nilの場合、quit-flagは特に効果がない。

Macro: with-local-quit body…

このマクロはbodyを順番に実行するが、たとえこの構成の外部でinhibit-quitが非nilでも、少なくともローカルにbody内でのquitを許す。このマクロはquitによりexitした場合はnil、それ以外はbody内の最後のフォームの値をリターンする。

inhibit-quitがnilの場合with-local-quitへのエントリーでbodyだけが実行され、quit-flagをセットすることにより通常のquitが発生する。しかし通常のquitが遅延されるようにinhibit-quitが非nilにセットされている場合、非nilのquit-flagは特別な種類のローカルquitを引き起こす。これはbodyの実行を終了して、quit-flagを非nilのままでwith-local-quitボディーをexitするので、許され次第(通常の)他のquitが発生する。bodyの先頭ですでにquit-flagが非nilの場合、即座にローカルquitが発生して結局ボディーは実行されない。

このマクロは主にタイマー、プロセスフィルター、プロセスセンチネル、pre-command-hook、post-command-hook、およびinhibit-quitが通常はtにバイドされている場所で役に立つ。

Command: keyboard-quit: この関数は(signal 'quit nil)によりquit条件をシグナルする。これはquitが行うことと同じである(エラーのsignalを参照)。

quitに使用するC-g以外の文字を指定できます。入力のモード内の関数set-input-modeを参照してください。

21.12 プレフィクスコマンド引数

ほとんどのEmacsコマンドはプレフィクス引数(prefix argument)を使用できます。プレフィクス引数はコマンド自身の前に数字を指定するものです(プレフィクス引数とプレフィクスキーを混同しないように)。プレフィクス引数は常に値により表され、nilのときはカレントでプレフィクス引数が存在しないことを意味します。すべてのコマンドはプレフィクス引数を使用するか、あるいは無視します。

プレフィクス引数には2つの表現があります。それはraw(生の、加工していない、原料のままの、未加工の)と数字(numeric)です。エディターコマンドループは内部的にraw表現を使用し、Lisp変数もその情報を格納するのにこれを使用しますが、コマンドはどちらかの表現を要求できます。

以下は利用できるrawプレフィクス引数の値です:

nilはプレフィクス引数がないことを意味する。これの数値的な値は1だが、多くのコマンドはnilと整数1を区別する。
整数はそれ自身を意味する。
整数の要素を1つもつリスト。プレフィクス引数のこの形式は、1つまたは数字無しの連続するC-uの結果である。数値的な値はリスト内の整数だが、そのようなリストと単独の整数を区別するコマンドがいくつかある。
シンボル-。これは後に数字をともなわないM--かC-u -がタイプされたことを示す。数値的に等価な値は-1だが、整数の-1をシンボルの-を区別するコマンドがいくつかある。

以下の関数をさまざまなプレフィクスで呼び出して、これらの可能なプレフィクスを説明しましょう:

(defun display-prefix (arg)
  "rawプレフィクス引数の値を表示する。"
  (interactive "P")
  (message "%s" arg))

以下はさまざまなrawプレフィクス引数でdisplay-prefixを呼び出した結果です:

        M-x display-prefix  -| nil

C-u     M-x display-prefix  -| (4)

C-u C-u M-x display-prefix  -| (16)

C-u 3   M-x display-prefix  -| 3

M-3     M-x display-prefix  -| 3      ; (C-u 3と同じ)

C-u -   M-x display-prefix  -| -

M--     M-x display-prefix  -| -      ; (C-u -と同じ)

C-u - 7 M-x display-prefix  -| -7

M-- 7   M-x display-prefix  -| -7     ; (C-u -7と同じ)

Emacsにはプレフィクス引数を格納するための2つの変数prefix-argとcurrent-prefix-argがあります。他のコマンドにたいしてプレフィクス引数をセットアップするuniversal-argumentのようなコマンドは、プレフィクス引数をprefix-arg内に格納します。対照的にcurrent-prefix-argはカレントコマンドにプレフィクス引数を引き渡すので、これらの変数をセットしても将来のコマンドにたいするプレフィクス引数に効果はありません。

コマンドは通常はinteractive内で、プレフィクス引数にたいしてrawと数値のどちらの表現を使用するかを指定します(interactiveの使用を参照)。そのかわりに関数は変数current-prefix-arg内のプレフィクス引数の値を直接調べるかもしれませんが、これは明確さで劣ります。

Function: prefix-numeric-value arg: この関数はargの有効なrawプレフィクス引数の数値的な意味をリターンする。引数はシンボル、数字、またはリストかもしれない。これがnilの場合は、値1がリターンsare,-の場合は-1がリターンされる。これが数字の場合は、その数字がリターンされる。リスト(数字であるべき)の場合は、そのリストのCARがリターンされる。

Variable: current-prefix-arg: この変数はカレントのコマンドにたいするrawプレフィクス引数を保持する。コマンドはこの変数を直接調べるかもしれないが、この変数にたいするアクセスには通常は(interactive "P")を使用する。

Variable: prefix-arg: この変数の値は次の編集コマンドにたいするrawプレフィクス引数である。後続のコマンドにたいしてプレフィクス引数を指定するuniversal-argumentのようなコマンドは、この変数をセットすることにより機能する。

Variable: last-prefix-arg: rawプレフィクス引数の値は、前のコマンドにより使用された値である。

以下のコマンドは、後続のコマンドにたいしてプレフィクス引数をセットアップするために存在します。これらを他の用途で呼び出さないでください。

Command: universal-argument: このコマンドは入力を読み取り。後続のコマンドにたいするプレフィクス引数を指定する。何をしているかわかっているのでなければ、このコマンドを自分で呼び出してはならない。

Command: digit-argument arg: このコマンドは、後続のコマンドにたいしてプレフィクス引数を追加する。引数argはこのコマンドの前のrawプレフィクス引数であり、これはプレフィクス引数を更新するために使用される。何をしているかわかっているのでなければ、このコマンドを自分で呼び出してはならない。

Command: negative-argument arg: このコマンドは、次のコマンドにたいして数引数を追加する。引数argはこのコマンドの前のrawプレフィクス引数であり、この値に負の符号が付されて新しいプレフィクス引数を構築する。何をしているかわかっているのでなければ、このコマンドを自分で呼び出してはならない。

21.13 再帰編集

Emacsスタートアップ時に、自動的にEmacsコマンドループにエンターします。このトップレベルのコマンドループ呼び出しは決してexitせず、Emacs実行中は実行を続けます。Lispプログラムもコマンドループを呼び出せます。これは複数のコマンドループを活性化するため、これを再帰編集(recursive editing)と呼んでいます。再帰編集レベルは、呼び出したコマンドが何であれそれをサスペンドして、そのコマンドを再開する前にユーザーが任意の編集を行うことを可能にする効果をもちます。

再帰編集の間に利用可能なコマンドは、トップレベルの編集ループ内で利用できるコマンドと同じであり、キーマップ内で定義されます。数少ない特別なコマンドだけが再帰編集レベルをexitし、他のコマンドは再帰編集レベルが終了したときに再帰編集レベルからリターンします(exitするための特別なコマンドは常に利用できますが、再帰編集が行われていないときは何も行いません)。

再帰コマンドループを含むすべてのコマンドループは、コマンドループから実行されたコマンド内のエラーによりそのループをexitしないように、汎用エラーハンドラーをセットアップします。

ミニバッファー入力は、特殊な再帰編集です。これは、ミニバッファーとミニバッファーウィンドウの表示を有効にするなどの欠点をもちますが、それはあなたが思うより少ないでしょう。ミニバッファー内では特定のキーの振る舞いが異なりますが、これははミニバッファーのローカルマップによるものです。ウィンドウを切り替えれば、通常のEmacsコマンドを使用できます。

再帰編集レベルを呼び出すには、関数をrecursive-editを呼び出します。この関数はコマンドループを含んでいます。さらにexitをthrowすることにより再帰編集レベルのexitを可能にする、タグexitをともなうcatch呼び出しも含んでいます(明示的な非ローカル脱出: catchとthrowを参照)。t以外の値をthrowした場合、recursive-editは通常それを呼び出した関数にリターンします。コマンドC-M-c(exit-recursive-edit)がこれを行います。値tをthrowすることによりrecursive-editがquitされるので、1レベル上位のコマンドループに制御がリターンされます。これはabortと呼ばれ、C-](abort-recursive-edit)がこれを行います。

Most applications should not use recursive editing, except as part of using the minibuffer. Usually it is more convenient for the user if you change the major mode of the current buffer temporarily to a special major mode, which should have a command to go back to the previous mode. (The e command in Rmail uses this technique.) Or, if you wish to give the user different text to edit recursively, create and select a new buffer in a special mode. In this mode, define a command to complete the processing and go back to the previous buffer. (The m command in Rmail does this.)

再帰編集はデバッグに便利です。一種のブレークポイントとして関数定義内にdebugを挿入して、関数がそこに達したときにその箇所を調べることができます。debugは再帰編集を呼び出しますが、デバッガのその他の機能も提供します。

query-replace内でC-rをタイプしたときやC-x q(kbd-macro-query)を使用したときも、再帰編集レベルが使用されます。

Command: recursive-edit

この関数はエディターコマンドループを呼び出す。これはユーザーに編集を開始させるために、Emacsの初期化により自動的に呼び出されるLispプログラムから呼び出されたときは、再帰編集レベルにエンターする。

カレントバッファーが選択されたウィンドウのバッファーと異なる場合、recursive-editはカレントバッファーの保存とリストアを行う。それ以外では、バッファーを切り替えた場合には、recursive-editがリターンした後その切り替えたバッファーがカレントになる。

以下の例では、関数simple-recが最初にポイントを1単語分進めてからメッセージをエコーエリアにプリントして再帰編集にエンターする。その後ユーザーは望む編集を行い、C-M-cをタイプすれば再帰編集をexitして、simple-recの実行を継続できる。

(defun simple-rec ()
  (forward-word 1)
  (message "Recursive edit in progress")
  (recursive-edit)
  (forward-word 1))
     ⇒ simple-rec
(simple-rec)
     ⇒ nil

Command: exit-recursive-edit: この関数は最内の再帰編集(ミニバッファー入力を含む)からexitする。関数の実質的な定義は(throw 'exit nil)である。

Command: abort-recursive-edit: この関数は、再帰編集をexitした後にquitをシグナルすることにより、最内の再帰編集(ミニバッファー入力を含む)を要求したコマンドをabortする。関数の実質的な定義は(throw 'exit t)である。quitを参照のこと。

Command: top-level: この関数はすべての再帰編集レベルをexitする。これはすべての計算を直接抜け出してメインのコマンドループに戻り、値をリターンしない。

Function: recursion-depth: この関数は再帰編集のカレントの深さをリターンする。アクティブな再帰編集が存在しない場合は、0をリターンする。

21.14 コマンドの無効化

コマンドを無効化(disabling a command)とは、それを実行可能にする前にユーザーによる確認を要求するようにコマンドをマークすることです。無効化は初めてのユーザーを混乱させるかもしれないコマンドにたいして、アクシデントによりそのコマンドが使用されるのを防ぐために使用されます。

コマンド無効化の低レベルにおけるメカニズムは、そのコマンドにたいするLispシンボルのdisabledプロパティに非nilをputすることです。これらのプロパティは、通常はユーザーのinitファイル(initファイルを参照)で以下のようなLisp式によりセットアップされます:

(put 'upcase-region 'disabled t)

いくつかのコマンドにたいしては、これらのプロパティがデフォルトで与えられています(これらを削除したい場合はinitファイルで削除できる)。

disabledプロパティの値が文字列の場合、そのコマンドが無効化されていることを告げるメッセージにその文字列が含まれます。たとえば:

(put 'delete-region 'disabled
     "この方法で削除されたテキストはyankで戻せない!\n")

無効化されたコマンドをインタラクティブに呼び出したときに何が起こるかの詳細は、See Disabling in The GNU Emacs Manualを参照してください。コマンドの無効化は、それをLispプログラムから関数として呼び出したときは効果がありません。

Command: enable-command command: その時点より、特別な確認なしでcommand(シンボル)が実行されることを許す。さらにユーザーのinitファイル(initファイルを参照)も修正するので、将来のセッションにもこれが適用される。

Command: disable-command command: その時点より、command(シンボル)の実行に特別な確認を要求する。さらにユーザーのinitファイル(initファイルを参照)も修正するので、将来のセッションにもこれが適用される。

Variable: disabled-command-function

この変数の値は関数であること。ユーザーが無効化されたコマンドを呼び出したときは、無効化されたコマンドのかわりにその関数が呼び出される。そのコマンドを実行するためにユーザーが何のキーをタイプしたかを判断するためにthis-command-keysを使用して、そのコマンド自体を探すことができる。

値がnilの場合もあり得る。その場合は、たとえ無効化されたコマンドでも、すべてのコマンドが通常に機能する。

デフォルトでは、値はユーザーに処理を行うか尋ねる関数である。

21.15 コマンドのヒストリー

コマンドループは複雑なコマンドを手軽に繰り返せるように、実行された複雑なコマンドのヒストリー(history: 履歴)を保持します。複雑なコマンド(complex command)とは、ミニバッファーを使用してinteractive引数を読み取るコマンドです。これにはM-xコマンド、M-:コマンド、およびinteractive指定によりミニバッファーから引数を読み取る任意のコマンドが含まれます。コマンド自身の実行の間に明示的にミニバッファーを使用するものは、複雑なコマンドとは判断されません。

Variable: command-history

この変数の値は最近実行された複雑なコマンドのリストであり、それぞれが評価されるべきフォームとして表現される。このリストは編集セッションの間、すべての複雑なコマンドを蓄積するが、最大サイズ(ミニバッファーのヒストリーを参照)に達したときは、もっとも古い要素が削除されて、新たな要素が追加される。

command-history
⇒ ((switch-to-buffer "chistory.texi")
    (describe-key "^X^[")
    (visit-tags-table "~/emacs/src/")
    (find-tag "repeat-complex-command"))

実際には、このヒストリーリストはミニバッファーヒストリーの特殊ケースであり、それは要素が文字列ではなく式であることです。

以前のコマンドを編集したり再呼び出しするためのコマンドがいくつかあります。コマンドrepeat-complex-commandおよびlist-command-historyは、ユーザーマニュアルで説明されています(Repetition in The GNU Emacs Manualを参照)。ミニバッファー内では、通常のミニバッファーヒストリーコマンドが理由できます。

21.16 キーボードマクロ

キーボードマクロ(keyboard macro)は、コマンドとして考えることが可能な、入力イベントの記録されたシーケンスであり、キー定義により作成されます。キーボードマクロのLisp表現は、イベントを含む文字列またはベクターです。キーボードマクロとLispマクロ(マクロを参照)を混同しないでください。

Function: execute-kbd-macro kbdmacro &optional count loopfunc

この関数は、イベントシーケンスとしてkbdmacroを実行する。kbdmacroが文字列かベクターの場合、たとえそれがユーザーによる入力であっても、その中のイベントは忠実に実行される。シーケンスは、単一のキーシーケンスであることを要求されない。キーボードマクロ定義は、通常は複数のキーシーケンスを結合して構成される。

kbdmacroがシンボルの場合、そのシンボルの関数定義はkbdmacroの箇所に使用される。それが別のシンボルの場合は、このプロセスを繰り返す。最終的に結果は文字列かベクターになる。結果がシンボル、文字列、ベクターでない場合は、エラーがシグナルされる。

引数countは繰り返すカウントであり、kbdmacroがその回数実行される。countが省略、またはnilの場合は1回実行される。0の場合、kbdmacroはエラーに出会うか検索が失敗するまで、何度も実行される。

loopfuncが非nilの場合、それはマクロの繰り返しごとに呼び出される、引数なしの関数である。loopfuncがnilをリターンすると、マクロの実行が停止する。

execute-kbd-macroの使用例は、単一イベントの読み取りを参照のこと。

Variable: executing-kbd-macro: この変数は、カレントで実行中のキーボードマクロを定義する文字列かベクターである。nilの場合、カレントで実行中のマクロは存在しない。マクロの実行により実行されたときに異なる振る舞いをするように、コマンドはこの変数をテストできる。この変数を自分でセットしてはならない。

Variable: defining-kbd-macro

この変数は、キーボードマクロの定義中のときだけ非nilである。マクロ定義中の間は異なる振る舞いをするように、コマンドはこの変数をテストできる。既存のマクロ定義に追加する間、値はappendになる。コマンドstart-kbd-macro、kmacro-start-macro、end-kbd-macroは、この変数をセットする。この変数を自分でセットしてはならない。

この変数は常にカレント端末にたいしてローカルであり、バッファーローカルにできない。複数の端末を参照のこと。

Variable: last-kbd-macro

この変数は、もっとも最近定義されたキーボードマクロの定義である。値は文字列、ベクター、またはnilである。

この変数は常にカレント端末にたいしてローカルであり、バッファーローカルにできない。複数の端末を参照のこと。

Variable: kbd-macro-termination-hook: これはキーボードマクロが終了したときに実行されるノーマルフックであり、何がキーボードマクロを終了させたか(マクロの最後に達したのか、あるいはエラーにより最後に達する前に終了したのか)は問わない。

22 キーマップ

入力イベントのコマンドバインディングは、キーマップ(keymap)と呼ばれるデータ構造に記録されます。キーマップ内の各エントリーは個別のイベント型(他のキーマップ、またはコマンド)に関連づけ(またはバインド)されます。イベント型がキーマップにバインドされる場合、そのキーマップは次の入力イベントを調べるために使用されます。これはコマンドが見つかるまで継続されます。このプロセス全体をキールックアップ(key lookup: キー照合)と呼びます。

22.1 キーシーケンス		Lispオブジェクトとしてのキーシーケンス。
22.2 キーマップの基礎		キーマップの基本概念。
22.3 キーマップのフォーマット		キーマップはLispオブジェクトとしてどのように見えるか。
22.4 キーマップの作成		キーマップを作成、コピーする関数。
22.5 継承とキーマップ		キーマップが他のキーマップのバインディングを継承する方法。
22.6 プレフィクスキー		キーマップの定義としてキーを定義する。
22.7 アクティブなキーマップ		Emacsがアクティブなキーマップでキーバインディングを探す方法。
22.8 アクティブなキーマップの検索		アクティブなマップ検索のLisp処理概要。
22.9 アクティブなキーマップの制御		各バッファーは標準(グローバル)のバインディングをオーバーライドするためのキーマップをもつ。マイナーモードもそれらをオーバーライドできる。
22.10 キーの照合		1つのキーマップから、あるキーのバインディングを探す。
22.11 キー照合のための関数		キールックアップを要求する方法。
22.12 キーバインディングの変更		キーマップ内でのキーの再定義。
22.13 コマンドのリマップ		キーマップはあるコマンドを他のコマンドに変換できる。
22.14 イベントシーケンス変換のためのキーマップ		イベントシーケンスを変換するキーマップ。
22.15 キーのバインドのためのコマンド		キーの再定義にたいするインタラクティブなインターフェイス。
22.16 キーマップのスキャン		ヘルプをプリントするためにすべてのキーマップを走査する。
22.17 メニューキーアップ		キーマップとしてキーマップを定義する。

22.1 キーシーケンス

キーシーケンス(key sequence)、短くはキー(key)とは、1つの単位を形成する1つ以上の入力イベントのシーケンスです。入力イベントには文字、ファンクションキー、マウスアクション、またはiconify-frameのようなEmacs外部のシステムイベントが含まれます(入力イベントを参照)。キーシーケンスにたいするEmacs Lispの表現は文字列かベクターです。特に明記しない限り、引数としてキーシーケンスを受け取るEmacs Lisp関数は両方の表現を処理することができます。

文字列表現では、たとえば、"a"はa、"2"は2を表すといったように、英数字はその文字自身を意味します。コントロール文字イベントは部分文字列"\C-"、メタ文字は"\M-"によりプレフィクスされます。たとえば"\C-x"はキーC-xを表します。それらに加えて、TAB、RET、ESC、DELなどのイベントはそれぞれ"\t"、"\r"、"\e"、"\d"で表されます。複雑なキーシーケンスの文字列表現は、イベント成分の文字列表現を結合したものです。したがって"\C-xl"はキーシーケンスC-x lを表します。

キーシーケンスにはファンクションキー、マウスボタンイベント、システムイベント、またはC-=やH-aのような文字列で表現できない非ASCII文字が含まれます。これらはベクターとして表現される必要があります。

ベクター表現ではベクターの各要素は1つの入力イベントをイベントのLisp形式で表します。入力イベントを参照してください。たとえば、ベクター[?\C-x ?l]はキーシーケンスC-x lを表します。

キーシーケンスを文字列やベクターによる表現で記述する例は、Init Rebinding in The GNU Emacs Manualを参照してください。

Function: kbd keyseq-text

この関数はテキストkeyseq-text(文字列定数)をキーシーケンス(文字列かベクターの定数)に変換する。keyseq-textの内容はC-x C-k RET(kmacro-edit-macro) コマンドにより呼び出されたバッファー内と同じ構文を使用するべきであ特にファンクションキーの名前は‘<…>’で囲まなければならない。Edit Keyboard Macro in The GNU Emacs Manualを参照のこと。

(kbd "C-x") ⇒ "\C-x"
(kbd "C-x C-f") ⇒ "\C-x\C-f"
(kbd "C-x 4 C-f") ⇒ "\C-x4\C-f"
(kbd "X") ⇒ "X"
(kbd "RET") ⇒ "\^M"
(kbd "C-c SPC") ⇒ "\C-c "
(kbd "<f1> SPC") ⇒ [f1 32]
(kbd "C-M-<down>") ⇒ [C-M-down]

22.2 キーマップの基礎

キーマップは、さまざまなキーシーケンスにたいしてキーバインディング(key binding)を指定するLispデータ構造です。

1つのキーマップが、個々のイベントにたいする定義を直接指定します。 A single keymap directly specifies definitions for individual events. 単一のイベントでキーシーケンスが構成されるとき、そのキーシーケンスのキーマップ内でのバインディングは、そのイベントにたいするそのキーマップの定義です。それより長いキーシーケンスのバインディングは対話的プロセスにより見つけ出されます。まず、最初のイベント(これ自身がキーマップでなければならない)の定義を探します。次にそのキーマップ内で2つ目のイベントを探すといったように、そのキーシーケンス内のすべてのイベントが処理されるまで、これを続けます。

あるキーシーケンスのバインディングがキーマップであるような場合、わたしたちはそのキーシーケンスをプレフィクスキー(prefix key)と呼び、それ以外の場合は(それ以上イベントを追加できないので)コンプリートキー(complete keylと呼んでいます。バインディングがnilの場合、わたしたちはそのキーを未定義(undefined)と呼びます。C-c、C-x、C-x 4などはプレフィクスキーの例です。X、RET、C-x 4 C-fなどは定義されたコンプリートキーの例です。C-x C-gやC-c 3などは未定義なコンプリートキーの例です。詳細はプレフィクスキーを参照してください。

キーシーケンスのバインディングを見つけ出すルールは、(最後のイベントの前までに見つかる)中間的なバインディングがすべてキーマップであると仮定します。もしそうでなければ、そのイベントシーケンスは単位を形成せず、実際の単一キーシーケンスではありません。言い換えると、任意の有効なキーシーケンスから1つ以上のイベントを取り除くと、常にプレフィクスキーにならなければなりません。たとえばC-f C-nはキーシーケンスではありません。C-fはプレフィクスキーではないので、C-fで始まるこれより長いシーケンスは、キーシーケンスであり得ないのです。

利用可能な複数イベントキーシーケンスのセットは、プレフィクスキーにたいするバインディングに依存します。したがって、これはキーマップが異なれば異なるかもしれず、バインディングが変更されたとき変更されるかもしれません。しかし、単一イベントキーシーケンスは適格性において任意のプレフィクスキーに依存しないので、常に単一のキーシーケンスです。

常に複数のプライマリーキーマップ(primary keymap: 主キーマップ)がアクティブであり、これらはキーバインディングを見つけるために使用されます。すべてのバッファーで共有されるグローバルキーマップ(global map)というキーマップが存在します。ローカルキーマップ(local keymap)は通常、特定のメジャーモードに関連します。そして0個以上のマイナーモードキーマップ(minor mode keymap)はカレントで有効なマイナーモードに属します(すべてのマイナーモードがキーマップをもつわけでなない)。ローカルキーマップは、対応するグローバルバインディングをshadow(優先される)します。マイナーモードキーマップは、ローカルキーマップとグローバルキーマップの両方をshadowします。詳細は、アクティブなキーマップを参照してください。

22.3 キーマップのフォーマット

キーマップはそれぞれ、CARがシンボルkeymapであるようなリストです。このリストの残りの要素は、そのキーマップのキーバインディングを定義します。関数定義がキーマップであるようなシンボルもキーマップです。あるオブジェクトがキーマップかどうかテストするには、関数keymapp(以下参照)を使用してください。

キーマップを開始するシンボルkeymapの後には、いくつかの種類の要素が出現します:

(type . binding): これは型typeのイベントにたいする1つのバインディングを指定する。通常のバインディングはそれぞれ、常に文字かシンボルであるような特定のイベント型(event type)のイベントに適用される。イベントの分類を参照のこと。この種のバインディングでは、bindingはコマンドである。
(type item-name . binding): これは、メニュー内でitem-nameとして表示されるシンプルなメニューアイテムでもあるようなバインディングを指定する。単純なメニューアイテムを参照のこと。
(type item-name help-string . binding): これは、ヘルプ文字列help-stringのシンプルなメニューアイテムである。
(type menu-item . details): これは、拡張されたメニューアイテムでもあるようなバインディングを指定する。これは他の機能も使用できる。拡張メニューアイテムを参照のこと。
(t . binding): これはデフォルトキーバインディング(default key binding)を指定する。キーマップの他の要素でバインドされないイベントは、バインディングとしてbindingが与えられる。デフォルトバインディングにより、利用可能なすべてのイベント型を列挙することなくバインドできる。デフォルトバインディングをもつキーマップは、明示的にnilにバインドされるイベント(以下参照)を除き、より低い優先度にあるすべてのキーマップをマスクする。
char-table: If an element of a keymap is a char-table, it counts as holding bindings for all character events with no modifier bits (see modifier bits): the element whose index is c is the binding for the character c. This is a compact way to record lots of bindings. A keymap with such a char-table is called a full keymap. Other keymaps are called sparse keymaps.
vector: This kind of element is similar to a char-table: the element whose index is c is the binding for the character c. Since the range of characters that can be bound this way is limited by the vector size, and vector creation allocates space for all character codes from 0 up, this format should not be used except for creating menu keymaps (see section メニューキーアップ), where the bindings themselves don’t matter.
string: キーにたいするバインディングを指定する要素は別として、キーマップは要素として文字列ももつことができる。これはoverallプロンプト文字列(overall prompt string: 全般的なプロンプト文字列)と呼ばれ、メニューとしてキーマップを使用することを可能にする。メニューの定義を参照のこと。
(keymap …): キーマップのある要素それ自身がキーマップの場合、それは外側のキーマップ内でこれが内側のキーマップとしてinline指定されているかのようにみなされる。これはmake-composed-keymap内で行なわれるような多重継承にたいして使用される。

バインディングがnilの場合、それは定義の構成要素ではありませんが、デフォルトバインディングや親キーマップ内のバインディングに優先されます。一方、nilのバインディングは、より低い優先度のキーマップをオーバーライドしませんしたがって、ローカルマップでnilのバインディングが与えられた場合、Emacsはグローバルマップのバインディングを使用します。

キーマップはメタ文字にたいするバインディングを直接記録しません。かわりに、メタ文字は１文字目がESC(または何であれmeta-prefix-charのカレント値)の、2文字のキーシーケンスをルックアップするものとみなされます。したがって、キーM-aは内部的にESC aで表され、そのグローバルバインディングは、esc-map内のaにたいするスロットで見つけることができます(プレフィクスキーを参照)。

この変換は文字にたいしてのみ適用され、ファンクションキーや他の入力イベントには適用されないので、M-endはESC endと何も関係ありません。

以下に例としてLispモードにたいするローカルキーマップ(sparseキーマップ)を挙げます。以下ではDEL、C-c C-z、C-M-q、C-M-xにたいするバインディングを定義しています(実際の値はメニューバインディングも含みますが、簡潔にするためここでは省略しています)。

lisp-mode-map
⇒

(keymap
 (3 keymap
    ;; C-c C-z
    (26 . run-lisp))

 (27 keymap
     ;; C-M-xはESC C-xとして扱われる
     (24 . lisp-send-defun))

 ;; この部分はlisp-mode-shared-mapから継承
 keymap
 ;; DEL
 (127 . backward-delete-char-untabify)

 (27 keymap
     ;; C-M-qはESC C-qとして扱われる
     (17 . indent-sexp)))

Function: keymapp object

この関数は、objectがキーマップならt、それ以外はnilをリターンする。より正確には、この関数はリストにたいしてそのCARがkeymapか、あるいはシンボルにたいしてその関数定義がkeymappかをテストする。

(keymapp '(keymap))
    ⇒ t

(fset 'foo '(keymap))
(keymapp 'foo)
    ⇒ t

(keymapp (current-global-map))
    ⇒ t

22.4 キーマップの作成

以下はキーマップを作成する関数です。

Function: make-sparse-keymap &optional prompt

この関数はエントリーをもたない新たなsparseキーマップを作成して、それをリターンする(sparseキーマップは、あなたが通常望む類のキーマップのこと)。make-keymapとは異なり、新たなキーマップは文字テーブルを含まず、何のイベントもバインドしない。

(make-sparse-keymap)
    ⇒ (keymap)

promptを指定した場合、それはキーマップにたいするoverallプロンプト文字列になる。これはメニューキーマップ(メニューの定義を参照)にたいしてのみ指定すべきである。overallプロンプト文字列をともなうキーマップがアクティブな場合は、次の入力イベントのルックアップにたいしてマウスメニューとキーボードメニューを常に提示する。これはコマンドループにたいして毎回キーボードメニューを提示するので、overallプロンプト文字列をメインマップ、メジャーモードマップ、マイナーモードマップに指定しないこと。

Function: make-keymap &optional prompt

この関数は、新たなfullキーマップを作成して、それをリターンする。このキーマップは修飾されないすべての文字にたいするスロットをもつ文字テーブル(文字テーブルを参照)を含む。この新たなキーマップは、初期状態ではすべての文字、およびその他の種類のイベントがnilにバインドされている。引数promptは、make-sparse-keymapのようにプロンプト文字列を指定する。

(make-keymap)
    ⇒ (keymap #^[nil nil keymap nil nil nil …])

fullキーマップは、多くのスロットを保持するときはsparseキーマップより効果的であり、少ししかスロットを保持しないときはsparseキーマップのほうが適している。

Function: copy-keymap keymap

This function returns a copy of keymap. This is almost never needed. If you want a keymap that’s like another yet with a few changes, you should use map inheritance rather than copying. I.e., something like:

(let ((map (make-sparse-keymap)))
  (set-keymap-parent map <theirmap>)
  (define-key map ...)
  ...)

When performing copy-keymap, any keymaps that appear directly as bindings in keymap are also copied recursively, and so on to any number of levels. However, recursive copying does not take place when the definition of a character is a symbol whose function definition is a keymap; the same symbol appears in the new copy.

(setq map (copy-keymap (current-local-map)))
⇒ (keymap

     ;; (これはメタ文字を実装する)
     (27 keymap
         (83 . center-paragraph)
         (115 . center-line))
     (9 . tab-to-tab-stop))

(eq map (current-local-map))
    ⇒ nil

(equal map (current-local-map))
    ⇒ t

22.5 継承とキーマップ

キーマップは、他のキーマップを継承することができ、この継承元のキーマップを親キーマップ(parent keymap)と呼びます。そのようなキーマップは、以下のようなキーマップです:

(keymap elements… . parent-keymap)

これの効果は、このキーマップがキールックアップ時にparent-keymapのすべてのバインディングを継承するが、それらにバインディングを追加したり、elementsでオーバーライドできるということです。

define-keyや他のキーバインディング関数を使用してparent-keymap内のバインディングを変更した場合、変更されたバインディングはelementsで作られたバインディングにshadowされない限り、継承されたキーマップ内で可視になります。逆は真ではありません。define-keyを使用して継承されたキーマップ内のバインディングを変更した場合、これらの変更はelements内に記録されますが、parent-keymapに影響はありません。

親キーマップからキーマップを構築するには、set-keymap-parentを使用するのが正しい方法です。親キーマップから直接キーマップを構築するコードがある場合は、かわりにset-keymap-parentを使用するようにプログラムを変更してください。

Function: keymap-parent keymap: これは、keymapの親キーマップをリターンする。keymapに親キーマップがない場合、keymap-parentはnilをリターンする。

Function: set-keymap-parent keymap parent

これはkeymapの親キーマップをparentにセットして、parentをリターンする。parentがnilの場合、この関数はkeymapに親キーマップを与えない。

keymapがサブマップ(プレフィクスキーにたいするバインディング)をもつ場合は、それらも新たな親キーマップを受け取り、それらのプレフィクスキーにたいしてparentが何を指定するかが反映される。

以下はtext-mode-mapから継承してキーマップを作成する方法を示す例です:

(let ((map (make-sparse-keymap)))
  (set-keymap-parent map text-mode-map)
  map)

非sparseキーマップも親キーマップをもつことができますが、便利とは言えません。非sparseキーマップは、修飾ビットをもたないすべての数値文字コードにたいするバインディングとして、たとえそれがnilであっても常に何かを指定するので、これらの文字のバインディングが親キーマップから継承されることは決してないのです。

複数のマップからキーマップを継承したいときがあるかもしれません。これにたいしては、関数make-composed-keymapが使用できます。

Function: make-composed-keymap maps &optional parent: この関数は、既存のキーマップから構成される新たなキーマップをリターンする。また、オプションで親キーマップparentから継承する。mapsには単一のキーマップ、または複数のキーマップのリストを指定できる。リターンされた新たなマップ内でキーをルックアップするとき、Emacsはmaps内のキーマップを順に検索してからparent内を検索する。この検索は最初のマッチで停止される。mapsのどれか1つのキーマップ内のnilバインディングは、parent内の任意のバインディングをオーバーライドするが、mapsにないキーマップの非nilバインディングはオーバーライドしない。

For example, here is how Emacs sets the parent of 【FIXME】たとえば、以下はbutton-buffer-mapとspecial-mode-mapの両方を継承するhelp-mode-mapのようなキーマップの親キーマップをEmacsがセットする方法です:

(defvar help-mode-map
  (let ((map (make-sparse-keymap)))
    (set-keymap-parent map
      (make-composed-keymap button-buffer-map special-mode-map))
    ... map) ... )

22.6 プレフィクスキー

プレフィクスキー(prefix key)とは、バインディングがキーマップであるようなキーシーケンスです。このキーマップは、プレフィクスキーを拡張するキーシーケンスが何を行うか定義します。たとえば、C-xはプレフィクスキーであり、これはキーマップを使用し、そのキーマップは変数ctl-x-mapにも格納されています。このキーマップはC-xで始まるキーシーケンスにたいするバインディングを定義します。

標準的なEmacsのプレフィクスキーのいくつかは、Lisp変数でも見い出すことができるキーマップを使用していますl:

esc-mapは、プレフィクスキーESCにたいするグローバルキーマップである。したがって、すべてのメタ文字にたいする定義は、このキーマップで見つけることができる。このマップは、ESC-prefixの関数定義でもある。
help-mapは、プレフィクスキーC-hにたいするグローバルキーマップである。
mode-specific-mapは、プレフィクスキーC-cにたいするグローバルキーマップである。このマップは実際にはモード特有(mode-specific)ではなくグローバルであるが、このプレフィクスキーは主にモード特有なバインディングに使用されるので、C-h b(display-bindings)の出力内のC-cに関する情報で、この名前は有意義な情報を提供する。
ctl-x-mapは、プレフィクスキーC-xにたいして使用されるグローバルキーマップである。このマップは、シンボルControl-X-prefixの関数セルを通して見つけることができる。
mule-keymapは、プレフィクスキーC-x RET にたいして使用されるグローバルキーマップである。
ctl-x-4-mapは、プレフィクスキーC-x 4にたいして使用されるグローバルキーマップである。
ctl-x-5-mapは、プレフィクスキーC-x 5にたいして使用されるグローバルキーマップである。
2C-mode-mapは、プレフィクスキーC-x 6にたいして使用されるグローバルキーマップである。
vc-prefix-mapは、プレフィクスキーC-x vにたいして使用されるグローバルキーマップである。
goto-mapは、プレフィクスキーM-gにたいして使用されるグローバルキーマップである。
search-mapは、プレフィクスキーM-sにたいして使用されるグローバルキーマップである。
facemenu-keymapは、プレフィクスキーM-oにたいして使用されるグローバルキーマップである。
Emacsの他のプレフィクスキーにはC-x @、C-x a i、C-x ESC、ESC ESCがある。これらは、特別な名前をもたないキーマップを使用する。

プレフィクスキーのキーマップバインディングは、プレフィクスキーに続くイベントをルックアップするために使用されます。(これは、関数定義がキーマップであるようなシンボルかもしれません。効果は同じですが、シンボルはプレフィクスキーにたいする名前の役割を果たします。) したがって、C-xのバインディングはシンボルControl-X-prefixであり、このシンボルの関数セルがC-xコマンドにたいするキーマップを保持します(ctl-x-mapの値も同じキーマップです)。

プレフィクスキー定義は、任意のアクティブなキーマップ内に置くことができます。プレフィクスキーとしてのC-c、C-x、C-h、ESCの定義はグローバルマップ内にもあるので、これらのプレフィクスキーは常に使用できます。メジャーモードとマイナーモードは、ローカルマップやマイナーモードのマップ内にプレフィクスキー定義を置くことにより、キーをプレフィクスキーとして再定義できます。アクティブなキーマップを参照してください。

あるキーが複数のアクティブなマップ内でプレフィクスキーとして定義されている場合、それぞれの定義がマージされて効果をもちます。まずマイナーモードキーマップ内で定義されたコマンド、次にローカルマップのプレフィクス定義されたコマンド、そしてグローバルマップのコマンドが続きます。

以下の例では、ローカルキーマップ内でC-pをC-xと等価なプレフィクスキーにしています。すると、C-p C-fにたいするバインディングは、C-x C-fと同様に関数find-fileになります。キーシーケンスC-p 6は、すべてのアクティブなキーマップで見つけることができません。

(use-local-map (make-sparse-keymap))
    ⇒ nil

(local-set-key "\C-p" ctl-x-map)
    ⇒ nil

(key-binding "\C-p\C-f")
    ⇒ find-file

(key-binding "\C-p6")
    ⇒ nil

Function: define-prefix-command symbol &optional mapvar prompt

この関数は、プレフィクスキーのバインディングとして使用するために、symbolを用意する。これはsparseキーマップを作成して、それをsymbolの関数定義として格納する。その後はsymbolにキーシーケンスをバインディングすると、そのキーシーケンスはプレフィクスキーになるだろう。リターン値はsymbolである。

この関数は、値がそのキーマップであるような変数としてもsymbolをセットする。しかしmapvarが非nilの場合は、かわりにmapvarを変数としてセットする。

promptが非nilの場合、これはそのキーマップにたいするoverallプロンプト文字列になる。プロンプト文字列はメニューキーマップにたいして与えられるべきである(メニューの定義を参照)。

22.7 アクティブなキーマップ

Emacsは多くのキーマップを含んでいますが、常にいくつかのキーマップだけがアクティブです。Emacsがユーザー入力を受け取ったとき、それは入力イベントに変換されて(イベントシーケンス変換のためのキーマップを参照)、アクティブなキーマップ内でキーバインディングが照合されます。

アクティブなキーマップは通常、(1) keymapプロパティにより指定されるキーマップ、(2) 有効なマイナーモードのキーマップ、(3) カレントバッファーのローカルキーマップ、(4) グローバルキーマップの順です。Emacsは入力キーシーケンスそれぞれにたいして、これらすべてのキーマップ内を検索します。

Of these usual keymaps, the highest-precedence one is specified by the keymap text or overlay property at point, if any. (For a mouse input event, Emacs uses the event position instead of point; アクティブなキーマップの検索を参照のこと。)

次に優先されるのは、有効なマイナーモードにより指定されるキーマップです。もしあれば、これらのキーマップは変数emulation-mode-map-alists、minor-mode-overriding-map-alist、minor-mode-map-alistにより指定されます。アクティブなキーマップの制御を参照してください。

次に優先されるのは、バッファーのローカルキーマップ(local keymap)で、これにはそのバッファー特有なキーバインディングが含まれます。ミニバッファーもローカルキーマップをもちます(ミニバッファーの概念を参照)。ポイント位置にlocal-mapテキスト、またはoverlayプロパティがある場合、それはバッファーのデフォルトローカルキーマップのかわりに使用するローカルキーマップを指定します。

ローカルキーマップは通常はそのバッファーのメジャーモードによりセットされます。同じメジャーモードをもつすべてのバッファーは、同じローカルキーマップを共有します。したがって、あるバッファーでローカルキーマップを変更するためにlocal-set-key(キーのバインドのためのコマンドを参照)を呼び出した場合、それは同じメジャーモードをもつ他のバッファーのローカルキーマップにも影響を与えます。

最後は、C-fのようなカレントバッファーとは関係なく定義されるキーバインディングを含む、グローバルキーマップ(global keymap)です。kこのキーマップは常にアクティブであり、変数global-mapにバインドされています。

Apart from the above usual keymaps, Emacs provides special ways for programs to make other keymaps active. Firstly, the variable overriding-local-map specifies a keymap that replaces the usual active keymaps, except for the global keymap. Secondly, the terminal-local variable overriding-terminal-local-map specifies a keymap that takes precedence over all other keymaps (including overriding-local-map); this is normally used for modal/transient keybindings (the function set-transient-map provides a convenient interface for this). See section アクティブなキーマップの制御, for details.

これらを使用するのがキーマップをアクティブにする唯一の方法ではありません。キーマップは、read-key-sequenceによるイベントの変換のような、他の用途にも使用されます。イベントシーケンス変換のためのキーマップを参照してください。

いくつかの標準的なキーマップのリストは、標準的なキーマップを参照してください。

Function: current-active-maps &optional olp position: これは、カレントの状況下でコマンドループによりキーシーケンスをルックアップするために使用される、アクティブなキーマップのリストをリターンする。これは通常、overriding-local-mapとoverriding-terminal-local-mapを無視するが、olpが非nilの場合には、それらのキーマップにも注意を払う。オプションでpositionにevent-startによりリターンされるイベント位置、またはバッファー位置を指定でき、key-bindingで説明されているようにキーマップを変更するかもしれない。

Function: key-binding key &optional accept-defaults no-remap position

この関数は、カレントのアクティブキーマップでkeyにたいするバインディングをリターンする。そのキーマップ内でkeyが未定義の場合、結果はnilになる。

引数accept-defaultsは、lookup-key(キー照合のための関数を参照)のようにデフォルトバインディングをチェックするかを制御する。

コマンドがリマップ(remap: 再マップ。コマンドのリマップを参照)されたとき、key-bindingは通常、実際に実行されるであろうリマップされたコマンドをリターンするように、コマンドのリマップを行う。しかし、no-remapが非nilの場合、key-bindingはリマップを無視して、keyにたいして直接指定されたバインディングをリターンする。

keyがマウスイベント(もしかしたらプレフィクスイベントが先行するかもしれない)で始まる場合、照合されるマップはそのイベントの位置を元に決定される。それ以外では、それらのマップはポイント値に基づき決定される。しかし、positionを指定することにより、これらをオーバーライドできる。positionが非nilの場合、それはバッファー位置かevent-startの値のようなイベント位置のいずれかである。その場合、照合されるマップはpositionに基づき決定される。

keyが文字列とベクターのいずれでもない場合、Emacsはエラーをシグナルする。

(key-binding "\C-x\C-f")
    ⇒ find-file

22.8 アクティブなキーマップの検索

以下は、macsがアクティブなキーマップを検索する方法を示す、Lisp処理概要です:

(or (if overriding-terminal-local-map
        (find-in overriding-terminal-local-map))
    (if overriding-local-map
        (find-in overriding-local-map)
      (or (find-in (get-char-property (point) 'keymap))
          (find-in-any emulation-mode-map-alists)
          (find-in-any minor-mode-overriding-map-alist)
          (find-in-any minor-mode-map-alist)
          (if (get-text-property (point) 'local-map)
              (find-in (get-char-property (point) 'local-map))
            (find-in (current-local-map)))))
    (find-in (current-global-map)))

ここで、find-inとfind-in-anyはそれぞれ、1つのキーマップとキーマップのalistを検索する仮の関数です。関数set-transient-mapがoverriding-terminal-local-map(アクティブなキーマップの制御を参照)をセットすることにより機能する点に注意してください。

上記の処理概要では、キーシーケンスがマウスイベント(マウスイベントを参照)で始まる場合、ポイント位置のかわりにそのイベント位置、カレントバッファーのかわりにそのイベントのバッファーが使用されます。これは特に、プロパティkeymapおよびlocal-mapをルックアップする方法に影響を与えます。display、before-string、after-stringプロパティ(特殊な意味をもつプロパティを参照)が埋め込まれていて、keymapまたはlocal-mapプロパティが非nilの文字列上でマウスイベントが発生した場合、それは基調となるバッファーテキストの対応するプロパティをオーバーライドします(バッファーテキストにより指定されたプロパティは無視される)。

アクティブなキーマップの1つでキーバインディングが見つかり、そのバインディングがコマンドの場合、検索は終了し、そのコマンドが実行されます。しかし、そのバインディングが値をもつ変数、または文字列の場合、Emacsは入力キーシーケンスをその変数の値、または文字列で置き換えて、アクティブなキーマップの検索を再開します。キーの照合を参照してください。

最終的に見つかったコマンドもリマップされるかもしれません。コマンドのリマップを参照してください。

22.9 アクティブなキーマップの制御

Variable: global-map

この変数は、Emacsキーボード入力をコマンドにマップするデフォルトのグローバルキーマップを含む。通常は、このキーマップがグローバルキーマップである。デフォルトグローバルキーマップは、self-insert-commandをすべてのプリント文字にバインドするfullキーマップである。

これはグローバルキーマップ内のバインディングを変更する通常の手段だが、この変数に開始時のキーマップ以外の値を割り当てるべきではない。

Function: current-global-map

この関数は、カレントのグローバルキーマップをリターンする。デフォルトグローバルキーマップとカレントグローバルキーマップのいずれも変更していない場合は、global-mapと同じ値になる。リターン値はコピーではなく参照である。これにdefine-keyなどの関数を使用すると、グローバルバインディングが変更されるだろう。

(current-global-map)
⇒ (keymap [set-mark-command beginning-of-line …
            delete-backward-char])

Function: current-local-map

この関数はカレントバッファーのローカルキーマップをリターンする。ローカルキーマップがない場合はnilをリターンする。以下の例では、(Lisp Interactionモードを使用する)*scratch*バッファーにたいするキーマップは、ESC(ASCIIコード27)にたいするエントリーが別のsparseキーマップであるようなsparseキーマップである。

(current-local-map)
⇒ (keymap
    (10 . eval-print-last-sexp)
    (9 . lisp-indent-line)
    (127 . backward-delete-char-untabify)

    (27 keymap
        (24 . eval-defun)
        (17 . indent-sexp)))

current-local-mapはローカルキーマップのコピーではなく参照をリターンする。これにdefine-keyなどの関数を使用すると、ローカルバインディングが変更されるだろう。

Function: current-minor-mode-maps: この関数は、カレントで有効なメジャーモードのキーマップリストをリターンする。

Function: use-global-map keymap

この関数は、keymapを新たなカレントグローバルキーマップにする。これはnilをリターンする。

グローバルキーマップの変更は、異例である。

Function: use-local-map keymap: この関数は、keymapをカレントバッファーの新たなローカルキーマップにする。keymapがnilの場合、そのバッファーはローカルキーマップをもたない。use-local-mapはnilをリターンする。ほとんどのメジャーモードコマンドは、この関数を使用する。

Variable: minor-mode-map-alist

この変数は、アクティブかどうかに関わらず、特定の変数の値にたいするキーマップを示すalistである。要素は、以下のようになる:

(variable . keymap)

キーマップkeymapは、 variableが非nil値をもつときはアクティブである。通常、variableはメジャーモードを有効、または無効にする変数である。キーマップとマイナーモードを参照のこと。

minor-mode-map-alistの要素が、minor-mode-alistの要素と異なる構造をもつことに注意されたい。マップは要素のCDRでなければならず、そうでなければ2つ目の要素にマップリストは用いられないだろう。CDRはキーマップ(リスト)、または関数定義がキーマップであるようなシンボルである。

1つ以上のマイナーモードキーマップがアクティブなとき、minor-mode-map-alist内で前のキーマップが優先される。しかし、互いが干渉しないようにマイナーモードをデザインすべきである。これを正しく行えば、順序は問題にならない。

マイナーモードについての詳細な情報は、キーマップとマイナーモードを参照のこと。minor-mode-key-binding(see section キー照合のための関数を参照)も確認されたい。

Variable: minor-mode-overriding-map-alist

この変数は、メジャーモードによる特定のマイナーモードにたいするキーバインディングのオーバーライドを可能にする。このalistの要素は、minor-mode-map-alistの要素のように、(variable . keymap)のような形式である。

ある変数がminor-mode-overriding-map-alistの要素として出現する場合、その要素により指定されるマップは、minor-mode-map-alist内の同じ変数にたいして指定される任意のマップを完全に置き換える。

すべてのバッファーにおいて、minor-mode-overriding-map-alistは自動的にバッファーローカルである。

Variable: overriding-local-map: この変数が非nilの場合は、バッファーのローカルキーマップ、テキストプロパティまたはoverlayによるキーマップ、マイナーモードキーマップのかわりに使用されるするキーマップを保持する。このキーマップが指定された場合、カレントグローバルキーマップ以外のアクティブだった他のすべてのマップがオーバーライドされる。

Variable: overriding-terminal-local-map

この変数が非nilの場合は、overriding-local-map、バッファーのローカルキーマップ、テキストプロパティまたはoverlayによるキーマップ、およびすべてのマイナーモードキーマップのかわりに使用されるキーマップを保持する。

この変数は、カレント端末にたいして常にローカルであり、バッファーローカルにできない。複数の端末を参照のこと。これはインクリメンタル検索モードの実装に使用される。

Variable: overriding-local-map-menu-flag

この変数が非nilの場合は、overriding-local-mapまたはoverriding-terminal-local-mapの値がメニューバーの表示に影響し得る。デフォルト値はnilなので、これらのマップ変数なメニューバーに影響をもたない。

これら2つのマップ変数は、たとえこれらの変数がメニューバー表示に影響し得るを与えない場合でも、メニューバーを使用してエンターされたキーシーケンスの実行には影響を与えることに注意されたい。したがって、もしメニューバーキーシーケンスが到着したら、そのキーシーケンスをルックアップ・実行する前に変数をクリアーすべきである。この変数を使用するモードは通常、何らかの方法でこれを行っている。これらのモードは通常“読み戻し(unread)”とexitにより処理されないイベントに応答する。

Variable: special-event-map: この変数は、スペシャルイベントにたいするキーマップを保持する。あるイベント型がこのキーマップ内でバインディングをもつ場合、それはスペシャルであり、そのイベントにたいするバインディングはread-eventにより直接実行される。スペシャルイベントを参照のこと。

Variable: emulation-mode-map-alists: This variable holds a list of keymap alists to use for emulation modes. It is intended for modes or packages using multiple minor-mode keymaps. Each element is a keymap alist which has the same format and meaning as minor-mode-map-alist, or a symbol with a variable binding which is such an alist. The active keymaps in each alist are used before minor-mode-map-alist and minor-mode-overriding-map-alist.

Function: set-transient-map keymap &optional keep-pred on-exit

この関数は一時的(transient)なキーマップとしてkeymapを追加する。一時的なキーマップは1つ以上の後続するキーにたいして、他のキーマップより優先される。

Normally, keymap is used just once, to look up the very next key. If the optional argument keep-pred is t, the map stays active as long as the user types keys defined in keymap; when the user types a key that is not in keymap, the transient keymap is deactivated and normal key lookup continues for that key.

The keep-pred argument can also be a function. In that case, the function is called with no arguments, prior to running each command, while keymap is active; it should return non-nil if keymap should stay active.

The optional argument on-exit, if non-nil, specifies a function that is called, with no arguments, after keymap is deactivated.

This function works by adding and removing keymap from the variable overriding-terminal-local-map, which takes precedence over all other active keymaps (see section アクティブなキーマップの検索).

22.10 キーの照合

キールックアップ(key lookup: キー照合)とは、与えられたキーマップからキーシーケンスのバインディングを見つけ出すことです。そのバインディングの使用や実行は、キールックアップの一部ではありません。

Key lookup uses just the event type of each event in the key sequence; the rest of the event is ignored. In fact, a key sequence used for key lookup may designate a mouse event with just its types (a symbol) instead of the entire event (a list). See section 入力イベント. Such a key sequence is insufficient for command-execute to run, but it is sufficient for looking up or rebinding a key.

キーシーケンスが複数イベントから構成されるとき、キールックアップはイベントを順に処理します。最初のイベントのバインディングが見つかったとき、それはキーマップでなければなりません。そのキーマップ内で2つ目のイベントを見つけ出し、そのキーシーケンス内のすべてのイベントが消費されるまで、このプロセスを続けます(故に、最後のイベントにたいして見つかったイベントはキーマップかどうかわからない)。したがって、キールックアッププロセスは、キーマップ内で単一イベントを見つけ出す、よりシンプルなプロセスで定義されます。これが行なわれる方法は、キーマップ内でそのイベントに関連するオブジェクトの型に依存します。

キーマップ内のイベント型ルックアップによる値発見を説明するために、キーマップエントリー(keymap entry)という用語を導入しましょう。(これにはメニューアイテムにたいするキーマップ内のアイテム文字列や、他の余計な要素は含まれません。なぜなら、lookup-keyや他のキーマップルックアップ関数が、リターン値にそれらを含まないからです。) 任意のLispオブジェクトがキーマップエントリーとしてキーマップに格納されるかもしれませんが、すべてがキールックアップに意味をもつわけではありません。以下のテーブルは、キーマップエントリーで重要な型です:

nil

nilは、それまでにルックアップに使用されたイベントが、未定義キーを形成することを意味する。最終的にキーマップがイベント型を調べるのに失敗して、デフォルトバインディングも存在しないときは、そのイベント型のバインディングがnilであるのと同じである。

command

それまでにルックアップに使用されたイベントがコンプリートキーを形成し、そのバインディングはcommandである。関数とは?を参照のこと。

array

array(文字列かベクター)は、キーボードマクロである。それまでにルックアップに使用されたイベントはコンプリートキーを形成し、そのバインディングはarrayである。詳細はキーボードマクロを参照のこと。

keymap

それまでにルックアップに使用されたイベントはプレフィクスキーを形成する。そのキーシーケンスの次のイベントは、keymap内でルックアップされる。

list

listの意味は、そのリストが何を含んでいるかに依存する:

listのCARがシンボルkeymapの場合、そのリストはキーマップであり、キーマップとして扱われる(上記参照)。
listのCARがlambdaの場合、そのリストはラムダ式である。これは関数とみなされ、そのように扱われる(上記参照)。キーバインディングとして正しく実行されるために、この関数はコマンドでなければならず、interactive指定をもたなければならない。コマンドの定義を参照のこと。

symbol

The function definition of symbol is used in place of symbol. If that too is a symbol, then this process is repeated, any number of times. Ultimately this should lead to an object that is a keymap, a command, or a keyboard macro.

キーマップおよびキーボードマクロ(文字列かベクター)は有効な関数ではないので、関数定義にキーマップ、文字列、ベクターをもつシンボルは、関数としては無効であることに注意されたい。しかし、キーバインディングとしては有効である。その定義がキーボードマクロの場合、そのシンボルはcommand-execute(interactiveな呼び出しを参照)の引数としても有効である。

シンボルundefinedは特記するに値する。これはそのキーを未定義として扱うことを意味する。厳密に言うと、そのキーは定義されているが、そのバインディングがコマンドundefinedなのである。しかし、このコマンドは未定義キーにたいして自動的に行われるのと同じことを行う。これは(dingを呼び出して)bellを鳴らすが、エラーはシグナルしない。

undefined is used in local keymaps to override a global key binding and make the key undefined locally. A local binding of nil would fail to do this because it would not override the global binding.

anything else

オブジェクトの他の型が見つかった場合、それまでにルックアップで使用されたイベントはコンプリートキーを形成し、そのオブジェクトがバインディングになるが、そのバインディングはコマンドとして実行不可能である。

In short, a keymap entry may be a keymap, a command, a keyboard macro, a symbol that leads to one of them, or nil.

22.11 キー照合のための関数

以下は、キールックアップに関連する関数および変数です。

Function: lookup-key keymap key &optional accept-defaults

この関数は、keymap内のkeyの定義をリターンする。このチャプターで説明されている、キーをルックアップする他のすべての関数がlookup-keyを使用する。以下は例である:

(lookup-key (current-global-map) "\C-x\C-f")
    ⇒ find-file

(lookup-key (current-global-map) (kbd "C-x C-f"))
    ⇒ find-file

(lookup-key (current-global-map) "\C-x\C-f12345")
    ⇒ 2

If the string or vector key is not a valid key sequence according to the prefix keys specified in keymap, it must be too long and have extra events at the end that do not fit into a single key sequence. Then the value is a number, the number of events at the front of key that compose a complete key.

accept-defaultsが非nilの場合、lookup-keyはkey内の特定のイベントにたいするバインディングと同様に、デフォルトバインディングも考慮する。それ以外では、lookup-keyは特定のkeyのシーケンスにたいするバインディングだけを報告し、明示的に指定したとき以外はデフォルトバインディングを無視する。(これを行うには、keyの要素としてtを与える。キーマップのフォーマットを参照のこと。)

keyがメタ文字(ファンクションキーではない)を含む場合その文字は暗黙にmeta-prefix-charの値と対応する非メタ文字からなる、2文字シーケンスに置き換えられる。したがって、以下に1つ目の例は、2つ目の例に変換されて処理される。

(lookup-key (current-global-map) "\M-f")
    ⇒ forward-word

(lookup-key (current-global-map) "\ef")
    ⇒ forward-word

read-key-sequenceとは異なり、この関数は指定されたイベントの情報を破棄する変更(キーシーケンス入力を参照)を行わない。特に、この関数はアルファベット文字を小文字に変更せず、ドラッグイベントをクリックイベントに変更しない。

Command: undefined: キーを未定義にするために、キーマップ内で使用される。これはdingを呼び出すが、エラーを起こさない。

Function: local-key-binding key &optional accept-defaults

この関数は、カレントのローカルキーマップ内の、keyにたいするバインディングをリターンする。カレントのローカルキーマップ内で未定義の場合は、nilをリターンする。

引数accept-defaultsは、lookup-key(上記)と同じように、デフォルトバインディングのチェックを制御する。

Function: global-key-binding key &optional accept-defaults

この関数は、カレントのグローバルキーマップ内で、コマンドkeyにたいするバインディングをリターンする。カレントのグローバルキーマップ内で未定義の場合は、nilをリターンする。

引数accept-defaultsは、lookup-key(上記)と同じように、デフォルトバインディングのチェックを制御する。

Function: minor-mode-key-binding key &optional accept-defaults

この関数は、アクティブなマイナーモードのkeyのバインディングを、リストでリターンする。より正確には、この関数は(modename . binding)のとうなペアーのalistをリターンする。ここでmodenameなそのマイナーモードを有効にする変数、bindingはそのモードでのkeyのバインディングである。keyがマイナーモードバインディングをみたない場合、値はnilである。

最初に見つかったバインディングがプレフィクス定義(キーマップ、またはキーマップとして定義されたシンボル)でない場合は、他のマイナーモード由来のすべての後続するバインディングは、完全にshadowされるため省略される。同様に、このリストはプレフィクスバインディングに後続する非プレフィクスバインディングは省略される。

引数accept-defaultsは、lookup-key(上記)と同じように、デフォルトバインディングのチェックを制御する。

User Option: meta-prefix-char

この変数はメタ/プレフィクス文字コードである。これはメタ文字をキーマップ内でルックアップできるように、2文字シーケンスに変換する。有用な結果を得るために、値はプレフィクスイベント(プレフィクスキーを参照)であること。デフォルト値は27で、これはESCにたいするASCIIコードである。

meta-prefix-charの値が27であるような限り、キールックアップは通常backward-wordコマンドとして定義されるM-bを、ESC bに変換する。しかし、meta-prefix-charを24(C-xのコード)にセットした場合、EmacsはM-bをC-x bに変換するだろうが、これの標準のバインディングはswitch-to-bufferコマンドである。以下に何が起こるかを示す(実際にこれを行ってはならない!):

meta-prefix-char                    ; デフォルト値
     ⇒ 27

(key-binding "\M-b")
     ⇒ backward-word

?\C-x                               ; 文字.の
     ⇒ 24                          ; プリント表現

(setq meta-prefix-char 24)
     ⇒ 24

(key-binding "\M-b")
     ⇒ switch-to-buffer            ; 今やM-bをタイプすると
                                    ;   C-x bをタイプしたようになる

(setq meta-prefix-char 27)          ; 混乱を避ける!
     ⇒ 27                          ; デフォルト値をリストア!

この単一イベントから２イベントへの変換は文字にたいしてのみ発生し、他の種類の入力イベントには発生しない。したがって、ファンクションキーM-F1はESC F1に変換されない。

22.12 キーバインディングの変更

キーのリバインド(rebind: 再バインド、再束縛)は、キーマップ内でそのキーのバインディングエントリーを変更することにより行います。グローバルキーマップ内のバインディングを変更した場合、その変更は(たとえローカルバインディングによりグローバルバインディングをshadowしているバッファーでは直接影響しないとしても)すべてのバッファーに影響します。カレントバッファーのローカルマップを変更した場合は、通常は同じメジャーモードを使用するすべてのバッファーに影響します。関数global-set-keyおよびlocal-set-keyは、これらの操作のための使いやすいインターフェイスです(キーのバインドのためのコマンドを参照)。より汎用的な関数define-keyを使用することもできます。その場合は、変更するマップを明示的に指定しなければなりません。

Lispプログラムでリバインドするキーシーケンスを選択するときは、さまざまなキーの使用についてのEmacsの慣習にしたがうようお願いします(キーバインディングの慣習を参照)。

リバインドするキーシーケンスの記述では、コントロール文字とメタ文字にたいして、特別なエスケープシーケンスを使用すると良いでしょう(文字列型を参照)。構文‘\C-’は後続する文字がコントロール文字でることを意味し、‘\M-’は後続する文字がメタ文字であることを意味します。したがって、文字列"\M-x"は1つのM-x、"\C-f"は1つのC-f、"\M-\C-x"および"\C-\M-x"は1つのC-M-xとして読み取られます。ベクター内でも、このエスケープシーケンス、および文字列では使用できない他のエスケープシーケンスを使用できます。1例は‘[?\C-\H-x home]’です。文字型を参照してください。

キー定義、およびルックアップ関数は、ベクターであるようなキーシーケンス内のイベント型にたいして、別の構文を受け入れます。修飾名に基本イベント(文字かファンクションキー名)を付加したものを含むリストを使用できます。たとえば、(control ?a)は?\C-a、(hyper control left)はC-H-leftと等価です。このようなリストの利点の1つは、コンパイル済みファイル内に修飾ビットの正確な数値コードが出現しないことです。

以下の関数は、keymapがキーマップでない場合、およびkeyがキーシーケンスを表す文字列やベクターでない場合はエラーをシグナルします。リストであるようなイベントにたいする略記として、イベント型(シンボル)を使用できます。kbd関数(キーシーケンスを参照)は、キーシーケンスを指定するための便利な方法です。

Function: define-key keymap key binding

この関数は、keymap内でkeyにたいするバインディングをセットする(keyが長さ2以上のイベントの場合、その変更は実際はkeymapから辿られる他のキーマップで行なわれる)。引数bindingには任意のLispオブジェクトを指定できるが、意味があるのは特定のオブジェクトだけである(意味のある型のリストは、キーの照合を参照のこと)。define-keyのリターン値はbindingである。

keyが[t]の場合、これはkeymap内でデフォルトバインディングをセットする。イベントが自身のバインディングをもたないとき、そのキーマップ内にデフォルトバインディングが存在するなら、Emacsコマンドループはそれを使用する。

keyのすべてのプレフィクスは、プレフィクスキー(キーマップにバインドされる)、または未定義でなけらばならず、それ以外はエラーがシグナルされる。keyのいくつかのプレフィクスが未定義の場合は、define-keyはそれをプレフィクスキーとして定義するので、残りのkeyは指定されたように定義できる。

前にkeymap内でkeyにたいするバインディングが存在しなかった場合は、新たなバインディングがkeymapの先頭に追加される。キーマップ内のバインディングの順序はキーボード入力にたいし影響を与えないが、メニューキーマップにたいしては問題となる(メニューキーアップを参照)。

以下は、sparseキーマップを作成して、その中にバインディングをいくつか作成する例である:

(setq map (make-sparse-keymap))
    ⇒ (keymap)

(define-key map "\C-f" 'forward-char)
    ⇒ forward-char

map
    ⇒ (keymap (6 . forward-char))

;; C-xにたいしsparseサブマップを作成し、
;; その中でfをバインドする
(define-key map (kbd "C-x f") 'forward-word)
    ⇒ forward-word

map
⇒ (keymap
    (24 keymap                ; C-x
        (102 . forward-word)) ;      f
    (6 . forward-char))       ; C-f

;; C-pをctl-x-mapにバインド
(define-key map (kbd "C-p") ctl-x-map)
;; ctl-x-map
⇒ [nil … find-file … backward-kill-sentence]

;; ctl-x-map内でC-fをfooにバインド
(define-key map (kbd "C-p C-f") 'foo)
⇒ 'foo

map
⇒ (keymap     ; ctl-x-map内のfooに注目
    (16 keymap [nil … foo … backward-kill-sentence])
    (24 keymap
        (102 . forward-word))
    (6 . forward-char))

C-p C-fにたいする新たなバインディングの格納は、実際にはctl-x-map内のエントリーを変更することにより機能し、これはデフォルトグローバルマップ内のC-p C-fとC-x C-fの両方のバインディングを変更する効果をもつことに注意されたい。

The function substitute-key-definition scans a keymap for keys that have a certain binding and rebinds them with a different binding. Another feature which is cleaner and can often produce the same results is to remap one command into another (see section コマンドのリマップ).

Function: substitute-key-definition olddef newdef keymap &optional oldmap

この関数は、keymap内でolddefにバインドされるすべてのキーについて、olddefをnewdefに置き換える。言い換えると、olddefが出現する箇所すべてをnewdefに置き換える。この関数はnilをリターンする。

たとえば、以下をEmacsの標準バインディングで行うと、C-x C-fを再定義する:

(substitute-key-definition
 'find-file 'find-file-read-only (current-global-map))

oldmapが非nilの場合は、どのキーをリバインドするかをoldmap内のバインディングが決定するよう、substitute-key-definitionの動作を変更する。リバインディングは依然としてoldmapではなく、keymapで発生する。したがって、他のマップ内のバインディングの制御下で、マップを変更することができる。たとえば、

(substitute-key-definition
  'delete-backward-char 'my-funny-delete
  my-map global-map)

これは、標準的な削除コマンドにグローバルにバインドされたキーにたいして、my-map内の特別な削除コマンドを設定する。

以下は、キーマップの置き換え(substitution)の前後を示す例である:

(setq map '(keymap
            (?1 . olddef-1)
            (?2 . olddef-2)
            (?3 . olddef-1)))
⇒ (keymap (49 . olddef-1) (50 . olddef-2) (51 . olddef-1))

(substitute-key-definition 'olddef-1 'newdef map)
⇒ nil

map
⇒ (keymap (49 . newdef) (50 . olddef-2) (51 . newdef))

Function: suppress-keymap keymap &optional nodigits

この関数は、self-insert-commandをコマンドundefinedにリマップ(コマンドのリマップを参照)することにより、fullキーマップのコンテンツを変更する。これは、すべてのプリント文字を未定義にする効果をもすので、通常のテキスト挿入は不可能になる。suppress-keymapはnilをリターンする。

nodigitsがnilの場合、suppress-keymapは数字がdigit-argument、-がnegative-argumentを実行するように定義する。それ以外は、残りのプリント文字と同じように、それらの文字も未定義にする。

suppress-keymap関数は、yankやquoted-insertのようなコマンドを抑制(suppress)しないので、バッファーの変更は可能である。バッファーの変更を防ぐには、バッファーを読み取り専用(read-only)にする(読み取り専用のバッファーを参照)。

この関数はkeymapを変更するので、通常は新たに作成したキーマップにたいして使用するだろう。するだろう。他の目的のために使用されている既存のキーマップに操作を行うと、恐らくトラブルの原因となる。たとえば、global-mapの抑制は、Emacsの使用をほとんど不可能に

この関数は、テキストの挿入が望ましくないメジャーモードの、ローカルキーマップ初期科に使用され得る。しかし、そのようなモードは通常はspecial-mode(基本的なメジャーモードを参照)から継承される。この場合、そのモードのキーマップは既に抑制済みのspecial-mode-mapから自動的に受け継がれる。以下にspecial-mode-mapが定義される方法を示す:

(defvar special-mode-map
  (let ((map (make-sparse-keymap)))
    (suppress-keymap map)
    (define-key map "q" 'quit-window)
    …
    map))

22.13 コマンドのリマップ

あるコマンドから他のコマンドへのリマップ(remap)には、特別な種類のキーバインディングが使用できます。この機能を使用するためには、ダミーイベントremapで始まり、その後にリマップしたいコマンド名が続くようなキーシーケンスにたいするキーバインディングを作成します。そして、そのバインディングにたいしては、新たな定義(通常はコマンド名だが、キーバインディングにたいして有効な他の任意の定義を指定可能)を指定します。

たとえば、Myモードというモードが、kill-lineのかわりに呼び出されるmy-kill-lineという特別なコマンドを提供するとします。これを設定するには、このモードのキーマップに以下のようなリマッピングが含まれるはずです:

(define-key my-mode-map [remap kill-line] 'my-kill-line)

その後は、my-mode-mapがアクティブなときは常に、ユーザーがC-k(kill-lineについてデフォルトのグローバルキーシーケンス)をタイプすると、Emacsはかわりにmy-kill-lineを実行するでしょう。

リマップはアクティブなキーマップでのみ行なわれることに注意してください。たとえば、ctl-x-mapのようなプレフィクスキーマップ内にリマッピングを置いても、そのようなキーマップはそれ自体がアクティブでないので、通常は効果がありません。それに加えて、リマップは1レベルを通じてのみ機能します。以下の例では、

(define-key my-mode-map [remap kill-line] 'my-kill-line)
(define-key my-mode-map [remap my-kill-line] 'my-other-kill-line)

これはkill-lineをmy-other-kill-lineにリマップしません。かわりに、通常のキーバインディングがkill-lineを指定する場合は、それがmy-kill-lineにリマップされます。通常のバインディングがmy-kill-lineを指定した場合は、my-other-kill-lineにリマップされます。

コマンドのリマップをアンドゥするには、以下のようにそれをnilにリマップします：

(define-key my-mode-map [remap kill-line] nil)

Function: command-remapping command &optional position keymaps

この関数は、カレントアクティブキーマップにより与えられる、command(シンボル)にたいするリマッピングをリターンする。commandがリマップされていない(これは普通の状況である)、またはシンボル以外の場合、この関数はnilをリターンする。positionは、key-bindingの場合と同様、使用するキーマップを決定するために、オプションバッファー位置、またはイベント位置をオプションで指定できる。

オプション引数keymapsが非nilの場合、それは検索するキーマップのリストを指定する。この引数は、positionが非nilの場合は無視される。

22.14 イベントシーケンス変換のためのキーマップ

read-key-sequence関数がキーシーケンス(キーシーケンス入力を参照)を読み取るときは、特定のイベントシーケンスを他のものに変換(translate)するために、変換キーマップ(translation keymaps)を使用します。input-decode-map、local-function-key-map、key-translation-map(優先順)は変換キーマップです。

Translation keymaps have the same structure as other keymaps, but are used differently: they specify translations to make while reading key sequences, rather than bindings for complete key sequences. As each key sequence is read, it is checked against each translation keymap. If one of the translation keymaps binds k to a vector v, then whenever k appears as a sub-sequence anywhere in a key sequence, that sub-sequence is replaced with the events in v.

For example, VT100 terminals send ESC O P when the keypad key PF1 is pressed. On such terminals, Emacs must translate that sequence of events into a single event pf1. This is done by binding ESC O P to [pf1] in input-decode-map. Thus, when you type C-c PF1 on the terminal, the terminal emits the character sequence C-c ESC O P, and read-key-sequence translates this back into C-c PF1 and returns it as the vector [?\C-c pf1].

変換キーマップは、(keyboard-coding-systemで指定された入力コーディングシステムを通じて)Emacsがキーボード入力をデコードした直後だけ効果をもちます。端末I/Oのエンコーディングを参照してください。

Variable: input-decode-map

この変数は、通常の文字端末上のファンクションキーから送信された文字シーケンスを記述するキーマップを保持する。

input-decode-mapの値は、通常はその端末のTerminfoかTermcapのエントリーに応じて、自動的にセットアップされるが、Lispの端末仕様ファイルの助けが必要なときもある。Emacsには、多くの一般的な端末の端末仕様ファイルが同梱されている。これらのファイルの主な目的は、TermcapやTerminfoから推定できないエントリーをinput-decode-map内に作成することである。端末固有の初期化を参照のこと。

Variable: local-function-key-map

この変数は、input-decode-mapと同じようにキーマップを保持するが、通常優先される解釈候補(alternative interpretation)に変換されるべきキーシーケンスを記述するキーマップを保持する。このキーマップはinput-decode-mapの後、key-translation-mapの前に適用される。

local-function-key-map内のエントリーは、マイナーモード、ローカルキーマップ、グローバルキーマップによるバインディングと衝突する場合は無視される。つまり、元のキーシーケンスが他にバインディングをもたない場合だけ、リマッピングが適用される。

local-function-key-mapがfunction-key-mapを継承するが、function-key-mapを直接使用すべきではない。

Variable: key-translation-map

この変数は、入力イベントを他のイベントに変換するために、input-decode-mapと同じように使用される、別のキーマップを保持する。input-decode-mapとの違いは、local-function-key-mapの前ではなく、後に機能する点である。このキーマップは、local-function-key-mapによる変換結果を受け取る。

input-decode-mapと同様、ただしlocal-function-key-mapとは異なり、このキーマップは入力キーシーケンスが通常のバインディングをもつかどうかかに関わらず適用される。しかし、このキーマップによりキーバインディングがオーバーライドされても、key-translation-mapでは実際のキーバインディングが効果をもち得ることに注意されたい。確かに、実際のキーバインディングはlocal-function-key-mapをオーバーライドし、したがってkey-translation-mapが受け取るキーシーケンスは変更されるだろう。明確にするためには、このような類の状況は避けたほうがよい。

key-translation-mapは、通常はself-insert-commandにバインディングされるような通常文字を含めて、ユーザーがある文字を他の文字にマップすることを意図している。

You can use input-decode-map, local-function-key-map, and key-translation-map for more than simple aliases, by using a function, instead of a key sequence, as the translation of a key. Then this function is called to compute the translation of that key.

キー変換関数は、引数を1つ受け取ります。この引数はread-key-sequence内で指定されるプロンプトです。キーシーケンスがエディターコマンドループに読み取られる場合は、nilです。ほとんどの場合、プロンプト値は無視できます。

関数が自身で入力を読み取る場合、その関数は後続のイベントを変更する効果をもつことができます。たとえば、以下はC-c hをハイパー文字に後続する文字とするために定義する方法の例です:

(defun hyperify (prompt)
  (let ((e (read-event)))
    (vector (if (numberp e)
                (logior (lsh 1 24) e)
              (if (memq 'hyper (event-modifiers e))
                  e
                (add-event-modifier "H-" e))))))

(defun add-event-modifier (string e)
  (let ((symbol (if (symbolp e) e (car e))))
    (setq symbol (intern (concat string
                                 (symbol-name symbol))))
    (if (symbolp e)
        symbol
      (cons symbol (cdr e)))))

(define-key local-function-key-map "\C-ch" 'hyperify)

22.14.1 通常のキーマップとの対話

そのキーシーケンスがコマンドにバインドされたとき、またはさらにイベントを追加してもコマンドにバインドされるシーケンスにすることができないとEmacsが判断したときに、キーシーケンスの終わりが検出されます。

これは、元のキーシーケンスがバインディングをもつかどうかに関わらず、input-decode-mapおよびkey-translation-mapを適用するとき、そのようなバインディングが変換の開始を妨げることを意味します。たとえば、前述のVT100の例に戻って、グローバルマップにC-c ESCを追加してみましょう。すると、ユーザーがC-c PF1をタイプしたとき、EmacsはC-c ESC O PをC-c PF1に変換するのに失敗するでしょう。これは、EmacsがC-x ESCの直後に読み取りを停止して、O Pは読み取られずに残るからです。この場合、ユーザーが実際にC-c ESCをタイプした場合、ユーザーが実際にESCを押下したのか、あるいはPF1を押下したのか判断するために、Emacsが待つべきではないのです。

この理由により、キーシーケンスの終わりがキー変換のプレフィクスであるようなキーシーケンスをコマンドにバインドするのは、避けたほうがよいでしょう。そのような問題を起こす主なサフィックス、およびプレフィクスはESC、M-O(実際はESC O)、M-[(実際はESC [)です。

22.15 キーのバインドのためのコマンド

このセクションでは、キーバインディングを変更するための便利な対話的インターフェイスを説明します。これらはdefine-keyを呼び出すことにより機能します。

ユーザーはinitファイルにたいしてシンプルなカスタマイズを行うとき、しばしばglobal-set-keyを使用します。たとえば、

(global-set-key (kbd "C-x C-\\") 'next-line)

または

(global-set-key [?\C-x ?\C-\\] 'next-line)

または

(global-set-key [(control ?x) (control ?\\)] 'next-line)

は、次の行に移動するようにC-x C-\を再定義します。

(global-set-key [M-mouse-1] 'mouse-set-point)

は、メタキーを押してマウスの第一ボタン(左ボタン)をクリックすると、クリックした箇所にポイントをセットするように再定義します。

バインドするキーのLisp指定に非ASCII文字のテキストを使用するときは、注意してください。マルチバイトとして読み取られたテキストがある場合には、Lispファイル内でマルチバイトテキストが読み取られるときのように(see section 非ASCII文字のロード)、マルチバイトとしてキーをタイプしなければなりません。たとえば、

(global-set-key "ö" 'my-function) ; bind o-umlaut

または

(global-set-key ?ö 'my-function) ; bind o-umlaut

をLatin-1のマルチバイト環境で使用した場合、これらのコマンドはLatin-1端末より送信されたバイトコード246(M-v)ではなく、コード246のマルチバイト文字に実際にバインドされます。このバインディングを使用するためには、適切な入力メソッド(Input Methods in The GNU Emacs Manualを参照)を使用して、キーボードをデコードする方法をEmacsに教える必要があります。

Command: global-set-key key binding

この関数は、カレントグローバルマップ内で、keyのバインディングをbindingにセットする。

(global-set-key key binding)
≡
(define-key (current-global-map) key binding)

Command: global-unset-key key

この関数は、カレントグローバルマップから、keyのバインディングを削除する。

プレフィクスとしてkeyを使用する、長いキーの定義の準備に使用するのも、この関数の1つの使い方である。keyが非プレフィクスのようなバインディングをもつ場合、この使い方は許されないだろう。たとえば、

(global-unset-key "\C-l")
    ⇒ nil

(global-set-key "\C-l\C-l" 'redraw-display)
    ⇒ nil

この関数は、以下のようにdefine-keyを使用するのと等しい:

(global-unset-key key)
≡
(define-key (current-global-map) key nil)

Command: local-set-key key binding

この関数は、カレントローカルキーマップ内のkeyのバインディングを、bindingにセットする。

(local-set-key key binding)
≡
(define-key (current-local-map) key binding)

Command: local-unset-key key

この関数は、カレントローカルキーマップから、keyのバインディングを削除する。

(local-unset-key key)
≡
(define-key (current-local-map) key nil)

22.16 キーマップのスキャン

このセクションでは、すべてのカレントキーマップをスキャンして、ヘルプ情報をプリントするために使用される関数を説明します。

Function: accessible-keymaps keymap &optional prefix

この関数は、(0個以上のプレフィクスキーを通じて)keymapから到達可能な、すべてのキーマップのリストをリターンする。リターン値は(key . map)のような形式の要素をもつ連想配列(alist)である。ここで、keyはkeymap内での定義がmapであるようなプレフィクスキーである。

alistの要素は、keyの長さにたいして昇順にソートされている。1つ目の要素は、常に([] . keymap)である。これは、指定されたキーマップがイベントなしのプレフィクスにより、自分自身からアクセス可能だからである。

prefixが与えられた場合、それはプレフィクスキーシーケンスである。その場合には、prefixで始まるプレフィクスキーをもつサブマップだけがaccessible-keymapsに含まれる。これらの要素の意味は、(accessible-keymaps)の値の場合と同様であり、いくつかの要素が省略されている点だけが異なる。

以下の例では、リターンされるalistにより、‘^[’と表示されるキーESCがプレフィクスキーであり、その定義がsparseキーマップ(keymap (83 . center-paragraph) (115 . foo))であること示される。

(accessible-keymaps (current-local-map))
⇒(([] keymap
      (27 keymap   ; 以降ESCにたいするこのキーマップが繰り返されることに注意
          (83 . center-paragraph)
          (115 . center-line))
      (9 . tab-to-tab-stop))

   ("^[" keymap
    (83 . center-paragraph)
    (115 . foo)))

また以下の例では、C-hは(keymap (118 . describe-variable)…)で始まるsparseキーマップを使用するプレフィクスキーである。他のプレフィクスC-x 4は、変数ctl-x-4-mapの値でもあるキーマップを使用する。イベントmode-lineは、ウィンドウの特別な箇所でのマウスイベントにたいするプレフィクスとして使用される、いくつかのダミーイベントのうちの1つである。

(accessible-keymaps (current-global-map))
⇒ (([] keymap [set-mark-command beginning-of-line …
                   delete-backward-char])

    ("^H" keymap (118 . describe-variable) …
     (8 . help-for-help))

    ("^X" keymap [x-flush-mouse-queue …
     backward-kill-sentence])

    ("^[" keymap [mark-sexp backward-sexp …
     backward-kill-word])

    ("^X4" keymap (15 . display-buffer) …)

    ([mode-line] keymap
     (S-mouse-2 . mouse-split-window-horizontally) …))

これらは実際に目にするであろうキーマップのすべてではない。

Function: map-keymap function keymap

関数map-keymapは、keymap内のバインディングそれぞれにたいして1回functionを呼び出す。呼び出す際の引数はイベント型と、そのバインディングの値の2つである。keymapに親キーマップがある場合は、その親キーマップのバインディングも含まれる。これは再帰的に機能する。つまり、その親キーマップ自身が親キーマップをもつ場合は、それのバインディングも含まれる、といった具合である。

これは、キーマップ内のすべてのバインディングを検証する、もっとも明快な方法である。

Function: where-is-internal command &optional keymap firstonly noindirect no-remap

この関数は、where-isコマンド(Help in The GNU Emacs Manualを参照)により使用されるサブルーチンである。これは、キーマップのセット内でcommandにバインドされる、(任意の長さの)キーシーケンスすべてのリストをリターンする。

引数commandには、任意のオブジェクトを指定できる。このオブジェクトは、すべてのキーマップエントリーにたいし、eqを使用して比較される。

keymapがnilの場合、overriding-local-mapの値とは無関係に(overriding-local-mapの値がnilであると装い)、カレントアクティブキーマップをマップとして使用する。keymapがキーマップの場合は、keymapとグローバルキーマップが検索されるマップとなる。keymapがキーマップのリストの場合は、それらのキーマップだけが検索される。

keymapにたいする式としては、通常はoverriding-local-mapを使用するのが最善である。その場合、where-is-internalは正にアクティブなキーマップを検索する。グローバルマップだけを検索するには、keymapの値に(keymap)(空のキーマップ)を渡せばよい。

firstonlyがnon-asciiの場合、値はすべての可能なキーシーケンスのリストではなく、最初に見つかったキーシーケンスを表す単一のベクターとなる。firstonlyがtの場合、値は最初のキーシーケンスだが、全体がASCII文字(またはメタ修飾されたASCII文字)で構成されるキーシーケンスが、他のすべてのキーシーケンスに優先され、リターン値がメニューバインディングになることは決してない。

If noindirect is non-nil, where-is-internal doesn’t look inside menu-items to find their commands. This makes it possible to search for a menu-item itself.

5つ目の引数no-remapは、この関数がコマンドリマッピング(コマンドのリマップを参照)を扱う方法を決定する。興味深いケースが2つある:

コマンドother-commandがcommandにリマップされる場合:: no-remapがnilの場合は、other-commandにたいするバインディングを探して、commandにたいするバインディングであるかのようにそれらを扱う。no-remapが非nilの場合は、それらのバインディングを探すかわりに、利用可能なキーシーケンスリストに、ベクター[remap other-command]を含める。
If command is remapped to other-command:: no-remapがnilの場合は、commandではなくother-commandにたいするバインディングをリターンする。no-remapが非nilの場合は、リマップされていることを無視して、commandにたいするバインディングをリターンする。

Command: describe-bindings &optional prefix buffer-or-name

この関数は、すべてのカレントキーバインディングのリストを作成して、*Help*という名前のバッファーにそれを表示する。テキストはモードごとにグループ化され、順番はマイナーモード、メジャーモード、グローバルバインディングの順である。

prefixが非nilの場合、それはプレフィクスキーである。その場合、リストに含まれるのはprefixで始まるキーだけになる。

複数の連続するASCIIコードが同じ定義をもつとき、それらは‘firstchar..lastchar’のようにまとめて表示される。この場合、それがどの文字に該当するかを理解するためには、そのASCIIコードを知っている必要がある。たとえば、デフォルトグローバルマップでは、文字‘SPC .. ~’は1行で記述される。SPCはASCIIの32，~はASCIIの126で、その間のすべての文字には、通常のプリント文字(アルファベット文字、数字、句読点など)が含まれる。これらの文字はすべて、self-insert-commandにバインドされる。

buffer-or-nameが非nilの場合、それはバッファー、またはバッファー名である。その場合、describe-bindingsはカレントバッファーのかわりに、そのバッファーのバインディングをリストする。

22.17 メニューキーアップ

キーマップは、キーボードキーやマウスボタンにたいするバインディング定義と同様に、メニューとして操作することができます。メニューは、通常はマウスにより操作されますが、キーボードでも機能させことができます。次の入力イベントにたいしてメニューキーマップがアクティブな場合は、キーボードメニュー機能がアクティブになります。

22.17.1 メニューの定義		メニューを定義するキーマップを作成する方法。
22.17.2 メニューとマウス		ユーザーがマウスでメニューを操作する方法。
22.17.3 メニューとキーボード		ユーザーがキーボードでメニューを操作する方法。
22.17.4 メニューの例		シンプルなメニューの作成。
22.17.5 メニューバー Bar		メニューバーのカスタマイズ方法。
22.17.6 ツールバー		イメージ行のツールバー。
22.17.7 メニューの変更		メニューへ新たなアイテムを追加する方法。
22.17.8 easy-menu		メニュー作成のための便利なマクロ。

22.17.1 メニューの定義

キーマップがoverallプロンプト文字列(overall prompt string)をもつ場合、そのキーマップはメニューとして動作します。overallプロンプト文字列とは、キーマップの要素として表される文字列です(キーマップのフォーマットを参照)。この文字列には、メニューコマンドの目的を記述します。Emacsは、(もしあれば)メニュー表示に使用されるツールキットに応じ、メニュータイトルとしてoverallメニュー文字列を表示します¹²。キーボードメニューもoverallプロンプト文字列を表示します。

プロンプト文字列をもつキーマップを構築するもっとも簡単な方法は、make-keymap、make-sparse-keymap(キーマップの作成を参照)、define-prefix-command(Definition of define-prefix-commandを参照)を呼び出すときに引数で文字列を指定する方法です。キーマップをメニューとして操作したくない場合は、これらの関数にたいしてプロンプト文字列を指定しないでください。

Function: keymap-prompt keymap: この関数は、keymapのoverallプロンプト文字列を、もしなければnilをリターンする。

メニューのアイテムは、そのキーマップ内のバインディングです。各バインディングはイベント型と定義を関連付けますが、イベント型はメニューの外見に何の意味ももちません(通常は、イベント型としてキーボードが生成できない擬似イベントのシンボルをメニューアイテムのバインディングに使用する)。メニュー全体は、これらのイベントにたいするキーマップ内のバインディングから生成されます。

メニュー内のアイテムの順序は、キーマップ内のバインディングの順序と同じです。define-keyは新たなバインディングを先頭に置くので、メニューアイテムの順序が重要な場合は、メニューの最後から先頭へメニューアイテムを定義する必要があります。既存のメニューにアイテムを追加するときは、define-key-afterを使用してメニュー内の位置を指定できます(メニューの変更を参照)。

22.17.1.1 単純なメニューアイテム

メニューアイテムを定義する単純(かつ初歩的)な方法は、何らかのイベント型(何のイベント型かは問題にならない)を以下のようにバインドすることです:

(item-string . real-binding)

CARのitem-stringは、メニュー内で表示される文字列です。これは短いほうがよく、1から3の単語が望ましいでしょう。この文字列は、対応するコマンドの動作を説明します。すべてのグラフィカルツールキットが非ASCIIテキストを表示できる訳ではないことに注意してください(キーボードメニューとGTK+ツールキットの大部分では機能するだろう)。

以下のように、ヘルプ文字列と呼ばれる2つ目の文字列を与えることもできます:

(item-string help . real-binding)

help specifies a help-echo string to display while the mouse is on that item in the same way as help-echo text properties (see Help display).

define-keyに関する限り、item-stringとhelp-stringは、そのイベントのバインディングの一部です。しかし、lookup-keyは単にreal-bindingだけをリターンし、そのキーの実行にはreal-bindingだけが使用されます。

real-bindingがnilの場合、メニューにitem-stringは表示されまづが、選択できなくなります。

If real-binding is a symbol and has a non-nil menu-enable property, that property is an expression that controls whether the menu item is enabled. Every time the keymap is used to display a menu, Emacs evaluates the expression, and it enables the menu item only if the expression’s value is non-nil. When a menu item is disabled, it is displayed in a fuzzy fashion, and cannot be selected.

メニューバーはメニューを調べる際に、どのアイテムが有効なのか再計算しません。これは、Xツールキットが事前にメニュー全体を要求するからです。メニューバーの再計算を強制するには、force-mode-line-updateを呼び出してください(モードラインのフォーマットを参照)。

22.17.1.2 拡張メニューアイテム

メニューアイテムの拡張フォーマットは、単純なフォーマットに比べて、より柔軟かつ明快です。拡張フォーマットでは、メニューアイテムにバインドのイベント型に、シンボルmenu-itemで始まるシンボルのリストを指定します。選択できない文字列にたいしては、以下のようなバインディングになります:

(menu-item item-name)

2つ以上のダッシュで始まる文字列は、リストのセパレーターを指定します。メニューセパレーターを参照してください。

選択可能な実際のメニューアイテムを定義するには、以下のような拡張フォーマットでバインドします:

(menu-item item-name real-binding
    . item-property-list)

ここで、item-nameはメニューアイテム文字列を評価する式です。つまり、文字列は底数である必要はありません。3つ目の引数real-bindingは、実行するコマンドです。リストの最後の要素item-property-listは、プロパティリストの形式をもつ、その他の情報を含みます。

以下は、サポートされるプロパティのテーブルです:

:enable form

formの評価結果は、そのアイテムを有効にするかどうかを決定する(非nilの場合は有効)。アイテムが無効な場合は、実際にクリックできない。

:visible form

formの評価結果は、そのアイテムを実際にメニューに表示するかどうかを決定する(非nilの場合は表示)。アイテムが非表示の場合は、そのアイテムが定義されていないかのようにメニューが表示される。

:help help

The value of this property, help, specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as help-echo text properties (see Help display). Note that this must be a constant string, unlike the help-echo property for text and overlays.

:button (type . selected)

このプロパティは、ラジオボタンおよびトグルボタンを定義する手段を提供する。CARのtypeは、:toggleか:radioのいずれかを指定する。CDRのselectedはフォームで、評価結果によりそのボタンがカレントで選択されているかどうかを指定する。

A toggle is a menu item which is labeled as either on or off according to the value of selected. The command itself should toggle selected, setting it to t if it is nil, and to nil if it is t. Here is how the menu item to toggle the debug-on-error flag is defined:

(menu-item "Debug on Error" toggle-debug-on-error
           :button (:toggle
                    . (and (boundp 'debug-on-error)
                           debug-on-error)))

これは、toggle-debug-on-errorが変数debug-on-errorをトグルするコマンドとして定義されていることにより機能する。

Radio buttons are a group of menu items, in which at any time one and only one is selected. There should be a variable whose value says which one is selected at any time. The selected form for each radio button in the group should check whether the variable has the right value for selecting that button. Clicking on the button should set the variable so that the button you clicked on becomes selected.

:key-sequence key-sequence

このプロパティは、そのメニューアイテムにより呼び出されるのと同じコマンドにバインドされるかもしれないキーシーケンスを指定する。正しいキーシーケンスを指定した場合は、メニュー表示の準備がより高速になる。

間違ったキーシーケンスを指定した場合は、何の効果もない。Emacsは、メニュー内のkey-sequenceを表示する前に、実際にそのkey-sequenceがそのメニューアイテムと等価なのか検証する。

:key-sequence nil

このプロパティは、そのメニューアイテムには等価なキーバインディングが通常は存在しないことを示す。このプロパティを使用することにより、Emacsはそのメニューアイテムにたいして等価なキーボード入力をキーマップから検索する必要がなくなるので、メニュー表示の準備時間が短縮される。

しかし、ユーザーがそのアイテムの定義をキーシーケンスにリバインドした場合、Emacsは:keysプロパティを無視して、結局は等価なキーボード入力を見つけ出す。

:keys string

このプロパティは、そのメニューにたいする等価なキーボード入力として表示される文字列stringを指定する。string内では、ドキュメント構成‘\\[...]’を使用できる。

:filter filter-fn

このプロパティは、メニューアイテムを直接計算する手段を提供する。このプロパティの値filter-fnは、引数が1つの関数で、呼び出し時の引数はreal-bindingである。この関数は、かわりに使用するバインディングをリターンするべきである。

Emacsは、メニューデータ構造を再表示、または操作する任意のタイミングでこの関数を呼び出し得るので、いつ呼び出されても安全なように関数を記述すべきである。

22.17.1.3 メニューセパレーター

メニューセパレーターは、テキストを表示するかわりに、水平ラインでメニューをサブパーツに分割する、メニューアイテムの一種です。メニューキーマップ内で、セパレーターは以下のように見えます:

(menu-item separator-type)

ここで、separator-typeは2つ以上のダッシュで始まる文字列です。

もっとも単純なケースでは、ダッシュだけでseparator-typeが構成されます。これはデフォルトのセパレーターを指定します(互換性のため、""と-もセパレーターとみなされる)。

separator-typeにたいする他の特定の値は、異なるスタイルのセパレーターを指定します。以下はそれらのテーブルです:

"--no-line"
"--space": 実際のラインではない、余分な垂直スペース。
"--single-line": メニューのforegroundカラーの一重ライン。
"--double-line": メニューのforegroundカラーの二重ライン。
"--single-dashed-line": メニューのforegroundカラーの一重ダッシュライン。
"--double-dashed-line": メニューのforegroundカラーの二重ダッシュライン。
"--shadow-etched-in": 3Dの窪んだ外観(3D sunken appearance)をもつ一重ライン。これはダッシュだけで構成されるセパレーターに使用されるデフォルトである。
"--shadow-etched-out": 3Dの浮き上がった外観(3D raised appearance)をもつ一重ライン。
"--shadow-etched-in-dash": 3Dの窪んだ外観(3D sunken appearance)をもつ一重ダッシュライン。
"--shadow-etched-out-dash": 3Dの浮き上がった外観(3D raised appearance)をもつ一重ダッシュライン。
"--shadow-double-etched-in": 3Dの窪んだ外観をもつ二重ライン。
"--shadow-double-etched-out": 3Dの浮き上がった外観をもつ二重ライン。
"--shadow-double-etched-in-dash": 3Dの窪んだ外観をもつ二重ダッシュライン。
"--shadow-double-etched-out-dash": 3Dの浮き上がった外観をもつ二重ダッシュライン。

2連ダッシュの後にコロンを追加して、1連ダッシュの後の単語の先頭の文字を大文字にすることにより、別のスタイルで名前を与えることもできます。つまり、"--:singleLine"は"--single-line"と等価です。

メニューセパレーターにたいして:enableや:visibleのようなキーワードを指定するために、長い形式を使用できます。

(menu-item separator-type nil . item-property-list)

たとえば:

(menu-item "--" nil :visible (boundp 'foo))

いくつかのシステムおよびディスプレイツールキットは、これらすべてのセパレータータイプを実際に処理しません。サポートされないタイプのセパレーターを使用した場合、メニューはサポートされている似た種別のセパレーターを表示します。

22.17.1.4 メニューアイテムのエイリアス

Sometimes it is useful to make menu items that use the same command but with different enable conditions. The best way to do this in Emacs now is with extended menu items; before that feature existed, it could be done by defining alias commands and using them in menu items. Here’s an example that makes two aliases for read-only-mode and gives them different enable conditions:

(defalias 'make-read-only 'read-only-mode)
(put 'make-read-only 'menu-enable '(not buffer-read-only))
(defalias 'make-writable 'read-only-mode)
(put 'make-writable 'menu-enable 'buffer-read-only)

When using aliases in menus, often it is useful to display the equivalent key bindings for the real command name, not the aliases (which typically don’t have any key bindings except for the menu itself). To request this, give the alias symbol a non-nil menu-alias property. Thus,

(put 'make-read-only 'menu-alias t)
(put 'make-writable 'menu-alias t)

は、make-read-onlyとmake-writableにたいするメニューアイテムに、read-only-modeのキーバインディングを表示します。

22.17.2 メニューとマウス

メニューキーマップがメニューを生成する通常の方法は、それをプレフィクスキーの定義とすることです。(Lispプログラムは明示的にメニューをポップアップして、ユーザーの選択を受け取ることができる。ポップアップメニューを参照のこと。)

プレフィクスキーがマウスイベントで終わる場合、ユーザーがマウスで選択できるように、Emacsは可視なメニューをポップアップすることによりメニューキーマップを処理します。ユーザーがメニューアイテムをクリックしたときは、そのメニューアイテムによりもたらされるバインディングの文字、またはシンボルが何であれ、イベントが生成されます(メニューが複数レベルをもつ場合やメニューバー由来の場合、メニューアイテムは1連のイベントを生成するかもしれない)。

メニューのトリガーにbutton-downイベントを使用するのが最善な場合もしばしばあります。その場合、ユーザーはマウスボタンをリリースすることにより、メニューアイテムを選択できます。

メニューキーマップがネストされたキーマップにたいするバインディングを含む場合、そのネストされたキーマップはサブメニュー(submenu)を指定します。それにはネストされたキーマップのアイテム文字列によりラベル付けされたメニューアイテムがあり、そのアイテムをクリックすることにより、指定されたサブメニューが自動的にポップアップされます。特別な例外として、メニューキーマップが単一のネストされたキーマップを含み、それ以外のメニューアイテムを含まない場合、そのメニューはネストされたキーマップの内容を、サブメニューとしてではなく、直接メニューに表示します。

しかし、XツールキットのサポートなしでEmacsをコンパイルした場合、またはテキスト端末の場合、サブメニューはサポートされません。ネストされたキーマップはメニューアイテムとして表示されますが、それをクリックしても、サブメニューは自動的にポップアップされません。サブメニューの効果を模倣したい場合は、ネストされたキーマップに‘@’で始まるアイテム文字列を与えることにより、これを行うことができます。これにより、Emacsは別個のメニューペイン(menu pane)を使用してネストされたキーマップを表示します。‘@’の後の残りのアイテム文字列は、そのペインのラベルです。XツールキットのサポートなしでEmacsをコンパイルした場合、またはメニューがテキスト端末で表示されている場合、メニューペインは使用されません。この場合、アイテム文字列の先頭の‘@’は、メニューラベル表示時には省略され、他に効果はありません。

22.17.3 メニューとキーボード

キーボードイベント(文字かファンクションキー)で終わるプレフィクスキーがメニューキーマップであるような定義をもつとき、そのキーマップはキーボードメニューのように動作します。ユーザーは、キーボードでメニューアイテムを選択して、次のイベントを指定します。

Emacsは、エコーエリアにキーボードメニュー、そのマップのoverallプロンプト文字列、その後に候補(そのマップのバインディングのアイテム文字列)を表示します。そのバインディングを一度に全部表示できない場合、ユーザーはSPCをタイプして、候補の次の行を確認できます。連続してSPCを使用するとメニューの最後に達し、その後は先頭へ巡回します。(変数menu-prompt-more-charはこのために使用する文字を指定する。デフォルトはSPC。)

ユーザーがメニューから望ましい候補を見つけたら、バインディングがその候補であるような、対応する文字をタイプする必要があります。

Variable: menu-prompt-more-char: この変数は、メニューの次の行を確認するために使用する文字を指定する。初期値は32で、これはSPCのコードである。

22.17.4 メニューの例

以下は、メニューキーマップを定義する、完全な例です。これは、メニューバー内の‘Edit’メニューにサブメニュー‘Replace’を定義して、その定義内で拡張メニューフォーマット(拡張メニューアイテムを参照)を使用します。例ではまずキーマップを作成して、それに名前をつけます:

(defvar menu-bar-replace-menu (make-sparse-keymap "Replace"))

次にメニューアイテムを定義します:

(define-key menu-bar-replace-menu [tags-repl-continue]
  '(menu-item "Continue Replace" tags-loop-continue
              :help "Continue last tags replace operation"))
(define-key menu-bar-replace-menu [tags-repl]
  '(menu-item "Replace in tagged files" tags-query-replace
              :help "Interactively replace a regexp in all tagged files"))
(define-key menu-bar-replace-menu [separator-replace-tags]
  '(menu-item "--"))
;; …

Note the symbols which the bindings are made for; these appear inside square brackets, in the key sequence being defined. In some cases, this symbol is the same as the command name; sometimes it is different. These symbols are treated as function keys, but they are not real function keys on the keyboard. They do not affect the functioning of the menu itself, but they are echoed in the echo area when the user selects from the menu, and they appear in the output of where-is and apropos.

The menu in this example is intended for use with the mouse. If a menu is intended for use with the keyboard, that is, if it is bound to a key sequence ending with a keyboard event, then the menu items should be bound to characters or real function keys, that can be typed with the keyboard.

定義が("--")のバインディングは、セパレーターラインです。実際のメニューアイテムと同様、セパレーターはキーシンボルをもち、この例ではseparator-replace-tagsです。1つのメニューが2つのセパレーターをもつ場合、それらは2つの異なるキーシンボルをもたなければなりません。

以下では、親メニュー内のアイテムとしてこのメニューがどのように表示されるかを記述しています:

(define-key menu-bar-edit-menu [replace]
  (list 'menu-item "Replace" menu-bar-replace-menu))

これは、シンボルmenu-bar-replace-menu自体ではなく、変数menu-bar-replace-menuの値であるサブメニューキーマップを組み込むことに注意してください。menu-bar-replace-menuはコマンドではないので、親メニューアイテムにそのシンボルを使用するのは無意味です。

同じreplaceメニューをマウスクリックに割り当てたい場合は、以下のようにこれを行うことができます:

(define-key global-map [C-S-down-mouse-1]
   menu-bar-replace-menu)

22.17.5 メニューバー Bar

Emacs usually shows a menu bar at the top of each frame. See Menu Bars in The GNU Emacs Manual. Menu bar items are subcommands of the fake function key menu-bar, as defined in the active keymaps.

To add an item to the menu bar, invent a fake function key of your own (let’s call it key), and make a binding for the key sequence [menu-bar key]. Most often, the binding is a menu keymap, so that pressing a button on the menu bar item leads to another menu.

When more than one active keymap defines the same function key for the menu bar, the item appears just once. If the user clicks on that menu bar item, it brings up a single, combined menu containing all the subcommands of that item—the global subcommands, the local subcommands, and the minor mode subcommands.

変数overriding-local-mapは通常、メニューバーのコンテンツを決定する際は無視されます。つまり、メニューバーはoverriding-local-mapがnilの場合にアクティブになるであろうキーマップから計算されます。アクティブなキーマップを参照してください。

以下は、メニューバーのアイテムをセットアップする例です:

;; (プロンプト文字列とともに)メニューキーマップを作成して
;; それをメニューバーアイテムの定義にする
(define-key global-map [menu-bar words]
  (cons "Words" (make-sparse-keymap "Words")))

;; メニュー内に具体的なサブコマンドを定義する
(define-key global-map
  [menu-bar words forward]
  '("Forward word" . forward-word))

(define-key global-map
  [menu-bar words backward]
  '("Backward word" . backward-word))

ローカルキーマップは、グローバルキーマップにより作成されたメニューバーアイテムにたいして、同じ偽ファンクションキーをundefinedにリバインドしてキャンセルすることができます。たとえば、以下はDiredが‘Edit’メニューバーアイテムを抑制する方法です:

(define-key dired-mode-map [menu-bar edit] 'undefined)

ここで、editは‘Edit’メニューバーアイテムにたいしてグローバルキーマップにより使用される偽ファンクションキーです。グローバルメニューバーアイテムを抑制する主な理由は、モード特有のアイテムのためのスペースを確保するためです。

Variable: menu-bar-final-items

通常メニューバーナーグローバルアイテムの後にローカルマップにより定義されるアイテムを表示する。

この変数は、通常の順番による位置ではなく、メニューの最後に表示するアイテムのための偽ファンクションキーのリストを保持する。デフォルト値は(help-menu)である。したがって、‘Help’メニューアイテムはメニューバーの最後、ローカルメニューアイテムの後に表示される。

Variable: menu-bar-update-hook: このノーマルフックは、メニューバーの再表示の前に、メニューバーのコンテンツを更新するための再表示により実行される。コンテンツを変化させる必要があるメニューの更新に使用できる。このフックは頻繁に実行されるので、フックが呼び出す関数は、通常の場合は長い時間を要さないことを確実にするよう助言する。

Emacsは、すべてのメニューバーアイテムの隣に、(もしそのようなキーバインディングが存在するなら)同じコマンドを実行するキーバインディングを表示します。これは、キーバインディングを知らないユーザーにたいして便利なヒントを与える役目をもちます。コマンドが複数のバインディングをもつ場合、通常Emacsは最初に見つけたバインディングを表示します。コマンドのシンボルプロパティ:advertised-bindingに割り当てることにより、特定のキーバインディングを指定できます。ドキュメント内でのキーバインディングの置き換えを参照してください。

22.17.6 ツールバー

ツールバー(tool bar)とは、フレームの最上部、メニューバー直下にある、クリック可能なアイコンの行のことです。Tool Bars in The GNU Emacs Manualを参照してください。Emacsは通常、グラフィカルなディスプレイ上でツールバーを表示します。

各フレームでは、ツールバーに何行分の高さを割り当てるかを、フレームパラメーターtool-bar-linesが制御します。値0は、ツールバーを抑制します。値が非0で、auto-resize-tool-barsが非nilの場合、指定されたコンテンツを維持するのに必要な分、ツールバーは拡大縮小されます。値がgrow-onlyの場合、ツールバーは自動的に拡大されますが、自動的に縮小はされません。

The tool bar contents are controlled by a menu keymap attached to a fake function key called tool-bar (much like the way the menu bar is controlled). So you define a tool bar item using define-key, like this:

(define-key global-map [tool-bar key] item)

where key is a fake function key to distinguish this item from other items, and item is a menu item key binding (see section 拡張メニューアイテム), which says how to display this item and how it behaves.

メニューキーマップの通常のプロパティ:visible、:enable、:button、:filterはツールバーバインディングでも役に立ち、いずれのプロパティも通常通りの意味をもちます。アイテム内のreal-bindingは、キーマップではなくコマンドでなければなりません。言い換えると、これはツールバーアイコンをプレフィクスキーとして定義するようには機能しないということです。

The :help property specifies a help-echo string to display while the mouse is on that item. This is displayed in the same way as help-echo text properties (see Help display).

これらに加えて、:imageプロパティも使用するべきでしょう。これは、ツールバー内にイメージを表示するには、このプロパティを使用します。

:image image

image is either a single image specification (see section イメージ) or a vector of four image specifications. If you use a vector of four, one of them is used, depending on circumstances:

item 0: アイテムが有効かつ選択されているとき使用される。
item 1: アイテムが有効かつ未選択のとき使用される。
item 2: アイテムが無効かつ選択されているとき使用される。
item 3: アイテムが無効かつ未選択のとき使用される。

GTK+およびNSバージョンのEmacsは、無効、および/または未選択のイメージをitem0から自動的に計算するので、item1からitem3は無視されます。

imageが単一イメージ様式の場合、Emacsはそのイメージにエッジ検出アルゴリズム(edge-detection algorithm)を適用することにより、ツールバーの無効な状態のボタンを描画します。

:rtlプロパティには、右から左に記述する言語のためのイメージ候補を指定します。現在のところ、これをサポートするのはGTK+バージョンのEmacsだけです。

メニューバーと同様、ツールバーはセパレーター(メニューセパレーターを参照)を表示できます。ツールバーのセパレーターは水平ラインではなく垂直ラインであり、1つのスタイルだけがサポートされます。これらは、ツールバーキーマップ内では(menu-item "--")エントリーで表されます。ツールバーのセパレーターでは、:visibleのようなプロパティはサポートされません。GTK+とNextstepのツールバーでは、セパレーターはネイティブに描画されます。それ以外では、セパレーターは垂直ラインイメージを使用して描画されます。

デフォルトツールバーは、コマンドシンボルのmode-classプロパティにspecialをもつメジャーモードにたいしては、編集に特化したアイテムは表示されないよう定義されています(メジャーモードの慣習を参照)。メジャーモードは、ローカルマップ内でバインディング[tool-bar foo]によって、グローバルバーにアイテムを追加するかもしれません。デフォルトツールバーの多くを適宜流用するのができないかもしれないため、デフォルトツールバーを完全に置き換えることは、いくつかのメジャーモードにとっては意味があります。デフォルトバインディングでtool-bar-mapを通じてインダイレクトすることにより、これを簡単に行うことができます。

Variable: tool-bar-map

デフォルトでは、グローバルマップは[tool-bar]を以下のようにバインドする:

(global-set-key [tool-bar]
                `(menu-item ,(purecopy "tool bar") ignore
                            :filter tool-bar-make-keymap))

関数tool-bar-make-keymapは、変数tool-bar-mapの値より、順に実際のツールバーマップをダイナミックに継承する。したがって、通常はそのマップを変更することにより、デフォルト(グローバル)ツールバーを調整すべきである。Infoモードのようないくつかのメジャーモードは、tool-bar-mapをバッファーローカルにして、それに異なるキーマップをセットすることにより、グローバルツールバーを完全に置き換える。

以下のような、ツールバーアイテムを定義するのに便利な関数があります。

Function: tool-bar-add-item icon def key &rest props

この関数は、tool-bar-mapを変更することにより、ツールバーにアイテムを追加する。使用するイメージはiconにより定義され、これはfind-imageに配置されたXPM、XBM、PBMのイメージファイルの拡張子を除いたファイル名(basename)である。たとえばカラーディスプレイ上では、値に‘"exit"’を与えるとexit.xpm、exit.pbm、exit.xbmの順に検索されるだろう。モノクロディスプレイでは、検索は‘.pbm’、‘.xbm’、‘.xpm’の順になる。使用するバインディングはコマンドdefで、keyはプレフィクスキーマップ内の偽ファンクションキーである。残りの引数propsは、メニューアイテム仕様に追加する、追加のプロパティリスト要素である。

あるローカルマップ内にアイテムを定義するためには、この関数呼び出しの周囲のletでtool-bar-mapをバインドする:

(defvar foo-tool-bar-map
  (let ((tool-bar-map (make-sparse-keymap)))
    (tool-bar-add-item …)
    …
    tool-bar-map))

Function: tool-bar-add-item-from-menu command icon &optional map &rest props

この関数は、既存のメニューバインディングと矛盾しないツールバーアイテムの定義に有用である。commandのバインディングはmap(デフォルトはglobal-map)内よりルックアップ(lookup: 照合)され、iconにたいするイメージ仕様はtool-bar-add-itemと同じ方法で見つけ出される。結果のバインディングはtool-bar-mapに配されるので、この関数の使用はグローバルツールバーアイテムに限定される。

mapには、[menu-bar]にバインドされた適切なキーマップが含まれていなければならない。残りの引数propsは、メニューアイテム仕様に追加する、追加のプロパティリスト要素である。

Function: tool-bar-local-item-from-menu command icon in-map &optional from-map &rest props: この関数は、非グローバルツールバーアイテムの作成に使用される。in-mapに定義を作成するローカルマップを指定する以外は、tool-bar-add-item-from-menuと同じように使用する。引数from-mapは、tool-bar-add-item-from-menuのmapと同様である。

Variable: auto-resize-tool-bars

この変数が非nilの場合、定義されたすべてのツールバーアイテムを表示するために、ツールバーは自動的にリサイズ — ただし、そのフレーム高さの1/4を超えてリサイズされることはない。

値がgrow-onlyの場合、ツールバーは自動的に拡張されるが、自動的に縮小はされない。ツールバーを縮小するために、ユーザーはC-lをエンターしてフレームを再描画する必要がある。

If Emacs is built with GTK+ or Nextstep, the tool bar can only show one line, so this variable has no effect.

Variable: auto-raise-tool-bar-buttons: この変数が非nilの場合、ツールバーアイテムの上をマウスが通過したとき、浮き上がった形式(raised form)で表示される。

Variable: tool-bar-button-margin: この変数は、ツールバーアイテムの周囲に追加する余白(extra margin)を指定する。値はピクセル数を整数で指定し、デフォルトは4である。

Variable: tool-bar-button-relief: この変数は、ツールバーアイテムの影(shadow)を指定する。値はピクセル数を整数で指定し、デフォルトは1である。

Variable: tool-bar-border: この変数は、ツールバーエリアの下に描画するボーダー高さを指定する。値が整数の場合は、高さのピクセル数である。値がinternal-border-width(デフォルト)かborder-widthのいずれの場合、ツールバーのボーダー高さは、そのフレームの対応するパラメーターとなる。

シフト、メタ等の修飾キーを押下した状態でのツールバーアイテムのクリックにたいして、特別な意味を付与できます。偽りのファンクションキーを通じて、元のアイテムに関連する追加アイテムをセットアップすることにより、これを行うことができます。より具体的には、追加アイテムは、元のアイテムの命名に使用されたのと同じ偽ファンクションキーの修飾されたバージョンを使用するべきです。

つまり、元のアイテムが以下のように定義されている場合、

(define-key global-map [tool-bar shell]
  '(menu-item "Shell" shell
              :image (image :type xpm :file "shell.xpm")))

シフト修飾とともに同じツールバーイメージをクリックしたときは、以下のような方法で定義することができます:

(define-key global-map [tool-bar S-shell] 'some-command)

ファンクションキーにたいして修飾を追加する方法についての詳細な情報は、ファンクションキーを参照してください。

22.17.7 メニューの変更

既存のメニューに新たなアイテムを挿入するときは、そのメニューの既存のアイテムの中の特定の位置にアイテムを追加したいと思うかもしれません。define-keyを使用してアイテムを追加した場合は通常、そのアイテムはメニューの先頭に追加されます。メニュー内の他の位置にアイテムを追加するには、define-key-afterを使用します:

Function: define-key-after map key binding &optional after

define-keyと同じように、map内にkeyにたいする値bindingのバインディングを定義するが、map内でそのバインディングの位置は、イベントafterにたいするバインディングの後になる。引数keyは長さ1 — 1要素だけのベクターか文字列にすべきである。しかしafterは単一のイベント型 — シーケンスではないシンボルか文字にすべきである。新たなバインディングは、afterにたいするバインディングの後に追加される。afterがt、または省略された場合、新たなバインディングはそのキーマップの最後に追加される。しかし、新たなバインディングは、すべての継承されたキーマップの前に追加される。

以下に例を示す:

(define-key-after my-menu [drink]
  '("Drink" . drink-command) 'eat)

これは、偽ファンクションキーDRINKにたいするバインディングを作成して、EATにたいするバインディングの直後に追加する。

以下に、Shellモードの‘Signals’メニュー内のアイテムbreakの後に、‘Work’と呼ばれるアイテムを追加する方法を示す:

(define-key-after
  (lookup-key shell-mode-map [menu-bar signals])
  [work] '("Work" . work-command) 'break)

22.17.8 easy-menu

以下のマクロは、ポップアップメニュー、および/またはメニューバーメニューを定義する便利な方法を提供します。

Macro: easy-menu-define symbol maps doc menu

このマクロは、menuにより与えるコンテンツのポップアップメニュー、および/またはメニューバーサブメニューを定義する。

symbolが非nilの場合、それはシンボルである。その場合、このマクロはドキュメント文字列docをもつ、メニューをポップアップ(ポップアップメニューを参照)する関数としてsymbolをを定義する。symbolはクォートされるべきではない。

symbolの値とは関係なく、mapsがキーマップの場合、メニューはメニューバーのトップレベルのメニュー(メニューバー Barを参照)としてmapsに追加される。これにはキーマップのリストも指定でき、その場合メニューはそれらのキーマップに個別に追加される。

menuの最初の要素は文字列でなければならず、それはメニューラベルの役割をもつ。値には、以下のキーワード/引数ペアーが任意の個数続くかもしれない:

:filter function: functionは1つの引数(他のメニューアイテムのリスト)で呼び出される関数でなければならず、メニュー内に表示される実際のアイテムをリターンする。
:visible include: includeには式を指定する。その式がnilに評価された場合、メニューは不可視になる。:includedは、:visibleにたいするエイリアスである。
:active enable: enableは式を。指定する。その式がnilに評価された場合、メニューは選択不可になる。:enableは、:activeにたいするエイリアスである。

menu内の残りの要素は、メニューアイテムである。

メニューアイテムには、3要素のベクター[name callback enable]を指定できる。ここでnameはメニューアイテム名(文字列)、callbackはアイテム選択時に実行するコマンド、または評価される式である。enableは式であり、nilに評価された場合、そのアイテムにたいする選択は無効になる。

かわりに、メニューアイテムは以下の形式をもつかもしれない:

   [ name callback [ keyword arg ]... ]

ここでnameとcallbackは上記と同じ意味をもち、オプションのkeywordとargの各ペアーは、以下のいずれかである:

:keys keys: keysは、メニューアイテムにたいする等価なキーボード入力(文字列)である。等価なキーボード入力は自動的に計算されるので、通常は必要ない。keysは、表示される前にsubstitute-command-keysにより展開される(ドキュメント内でのキーバインディングの置き換えを参照)。
:key-sequence keys: keysは、最初にメニューを表示されるかをする際、Emacsを高速化するヒントになる。等価なキーボード入力のないことが既知の場合は、nilを指定すべきである。それ以外では、メニューアイテムにたいする等価なキーボード入力を指定する文字列、またはベクターを指定すべきである。
:active enable: enableには式を指定する。その式がnilに評価された場合、アイテムは選択不可になる。enableは、:activeにたいするエイリアスである。
:visible include: includeには式を指定する。その式がnilに評価された場合、アイテムは不可視になる。:includedは、:visibleにたいするエイリアスである。
:label form: formは、メニューアイテムのラベル(デフォルトはname)の役目をもつ値を取得するために表示される式である。
:suffix form: formは、動的に評価される式であり、値はメニューエントリーのラベルに結合される。
:style style: styleは、メニューアイテムの型を記述するシンボルであり、toggle(チェックボックス)、radio(ラジオボタン)、またはそれ以外(通常のメニューアイテムであることを意味する)のいずれかである。
:selected selected: selectedには式を指定し、その式の値が非nilのときはチェックボックス、またはラジオボタンが選択状態になる。
:help help: helpは、メニューアイテムを説明する文字列である。

かわりに、メニューアイテムに文字列を指定できる。その場合、文字列は選択不可なテキストとしてメニューに表示される。ダッシュから構成される文字列は、セパレーターとして表示される(メニューセパレーターを参照)

かわりに、メニューアイテムにmenuと同じフォーマットのリストを指定できる。これはサブメニューとなる。

以下は、easy-menu-defineを使用して、メニューバー Bar内で定義したメニューと同等なメニューを定義する例である:

(easy-menu-define words-menu global-map
  "単語単位コマンドにたいするメニュー"
  '("Words"
     ["Forward word" forward-word]
     ["Backward word" backward-word]))

23 メジャーモードとマイナーモード

A mode is a set of definitions that customize Emacs behavior in useful ways. There are two varieties of modes: minor modes, which provide features that users can turn on and off while editing; and major modes, which are used for editing or interacting with a particular kind of text. Each buffer has exactly one major mode at a time.

このチャプターでは、メジャーモード、およびマイナーモードを記述する方法、モードラインにそれらを示す方法、そしてそれらのモードがユーザーが提供するフックを実行する方法について説明します。キーマップ(keymaps)や構文テーブル(syntax tables)のような関連するトピックについてはキーマップおよび構文テーブルを参照してください。

23.1 フック		フックの使い方と、フックを提供するコードの記述方法。
23.2 メジャーモード		メジャーモードの定義。
23.3 マイナーモード		マイナーモードの定義。
23.4 モードラインのフォーマット		モードラインに表示されるテキストのカスタマイズ。
23.5 Imenu		バッファーで作成された定義のメニューを提供する。
23.6 Font Lockモード		モードが構文に応じてテキストをハイライトする方法。
23.7 コードの自動インデント		メジャーモードにたいするインデントをEmacsに伝える方法。
23.8 Desktop Saveモード		Emacsセッション間でモードがバッファー状態を保存する方法。

23.1 フック

フック(hook)とは、既存のプログラムから特定のタイミングで呼び出される関数(複数可)を格納することができる変数のことです。Emacsはカスタマイズ用にフックを提供します。ほとんどの場合は、initファイル内(initファイルを参照)でフックをセットアップしますが、Lispプログラムもフックをセットできます。標準的なフック変数のリストは、標準的なフックを参照してください。

Emacsのほとんどのフックは、ノーマルフック(normal hooks)です。これらの変数は、引数なしで呼び出される、関数のリストを含んでいます。慣習により、フック名が‘-hook’で終わるフックは、そのフックがノーマルフックであることを意味します。わたしたちは、一貫した方法でフックを使用できるよう、すべてのフックが可能な限りノーマルフックとなるよう努力しています。

すべてのメジャーモードコマンドは、初期化の最終ステップの1つとして、モードフック(mode hook)と呼ばれるノーマルフックを実行するとみなされます。これにより、そのモードによりすでに作成されたバッファーローカル変数割り当てをオーバーライドすることにより、ユーザーがそのモードの動作をカスタマイズするのが簡単になります。ほとんどのマイナーモード関数も、最後にモードフックを実行します。しかし、フックは他のコンテキストでも使用されます。たとえばフックsuspend-hookは、Emacsが自身をサスペンド(Emacsのサスペンドを参照)する直前に実行されます。

フックにフック関数を追加するには、add-hook(フックのセットSetting Hooksを参照)を呼び出す方法が推奨です。フック関数は、funcall(関数とは?を参照)が受け入れる任意の種類の関数を指定できます。ほとんどのフック変数の初期値はvoidです。add-hookは、これを扱う方法を知っています。add-hookにより、グローバルフック、またはバッファーローカルフックのどちらを追加することも可能です。

フック変数の名前が‘-hook’で終わらない場合は、それが恐らくアブノーマルフック(abnormal hook)であることを示しています。こええは、フック関数が引数とともに呼ぶ出されること、または何らかの方法により、そのリターン値が使用されることを意味します。その関数の呼び出し方は、フックのドキュメントに記載されています。アブノーマルフックとして関数を追加するためにadd-hookを使用できますが、その関数はフック呼び出しの慣習にしたがって記述しななければなりません。慣習により、アブノーマルフックの名前は‘-functions’で終わります。

変数の名前が‘-function’で終わる場合、その値は関数のリストではなく単一の関数です。add-hookを、単一関数フックのように修正して使用することはできないので、かわりにadd-functionを使用します(Emacs Lisp関数にたいするアドバイスを参照)。

23.1.1 フックの実行

このセクションでは、ノーマルフックを実行するために使用される、run-hooksについて説明します。また、さまざまな種類のアブノーマルフックを実行する関数についても説明します。

Function: run-hooks &rest hookvars

この関数は、引数として1つ以上のノーマルフック変数名をとり、各フックを順に実行する。引数はそれぞれ、ノーマルフック変数であるようなシンボルであること。これらの引数は、指定された順に処理される。

フック変数の値が非nilの場合、その値は関数のリストであること。run-hooksは、すべての関数を引数なしで1つずつ呼び出す。

フック変数の値には、単一の関数(ラムダ式、またはシンボルの関数定義)も指定でき、その場合run-hooksはそれを喚び出す。しかし、この使い方は時代遅れである。

フック変数がバッファーローカルな場合、グローバル変数のかわりにそのバッファーローカル変数が使用される。しかし、そのバッファーローカル変数が要素tを含む場合は、そのグローバルフック変数も同様に実行されるだろう。

Function: run-hook-with-args hook &rest args: この関数は、hook内のすべての関数に、1つの引数argsを渡して喚び出すことにより、アブノーマルフックを実行する。

Function: run-hook-with-args-until-failure hook &rest args: This function runs an abnormal hook by calling each hook function in turn, stopping if one of them fails by returning nil. Each hook function is passed the arguments args. If this function stops because one of the hook functions fails, it returns nil; otherwise it returns a non-nil value.

Function: run-hook-with-args-until-success hook &rest args: This function runs an abnormal hook by calling each hook function, stopping if one of them succeeds by returning a non-nil value. Each hook function is passed the arguments args. If this function stops because one of the hook functions returns a non-nil value, it returns that value; otherwise it returns nil.

23.1.2 フックのセットSetting Hooks

以下は、Lisp Interactionモードのときに、モードフックを使用してAuto Fillモードをオンに切り替える例です:

(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)

Function: add-hook hook function &optional append local

この関数は、フック変数に関数functionを追加する手軽な方法である。ノーマルフックと同じように、アブノーマルフックにたいしてもこの関数を使用できる。functionには、正しい数の引数を受け付ける任意のLisp関数を指定できる。たとえば、

(add-hook 'text-mode-hook 'my-text-hook-function)

は、text-mode-hookと呼ばれるフックにmy-text-hook-functionを追加する。

hook内にfunctionがすでに存在する場合(比較にはequalを使用)、add-hookは2回目の追加を行わない。

functionのプロパティpermanent-local-hookが非nilの場合、kill-all-local-variables(またはメジャーモードを変更しても)、そのフック変数のローカル値から関数を削除しない。

ノーマルフックにたいして、フック関数は実行される順序に無関係であるようにデザインされるべきである。順序への依存は、トラブルを招く。とはいえ、その順序は予測可能である。通常、functionはフックリストの先頭に追加されるので、(他のadd-hook呼び出しがなければ)それは最初に実行される。オプション引数appendが非nilの場合、新たなフック関数はフックリストの最後に追加され、実行されるのも最後になる。

add-hookは、hookがvoidのとき、または値が単一の関数の場合、値を関数リストにセットまたは変更して、それらを扱うことができる。

localが非nilの場合、それはグローバルフックリストではなくバッファーローカルフックリストにfunctionを追加する。これはフックをバッファーローカルにして、そのバッファーローカルな値にtを追加する。バッファーローカルな値へのtの追加は、ローカル値と同じようにデフォルト値でもフック関数を実行するためのフラグである。

Function: remove-hook hook function &optional local

この関数は、フック変数hookからfunctionを削除する。これは、equalを使用してfunctionとhook要素を比較するので、その比較はシンボルとラムダ式の両方で機能する。

localが非nilの場合、それはグローバルフックリストではなく、バッファーローカルフックリストからfunctionを削除する。

23.2 メジャーモード

Major modes specialize Emacs for editing or interacting with particular kinds of text. Each buffer has exactly one major mode at a time. Every major mode is associated with a major mode command, whose name should end in ‘-mode’. This command takes care of switching to that mode in the current buffer, by setting various buffer-local variables such as a local keymap. See section メジャーモードの慣習. Note that unlike minor modes there is no way to “turn off” a major mode, instead the buffer must be switched to a different one.

Fundamentalモードと呼ばれるはもっとも特化されていないメジャーモードであり、モード特有な定義や変数セッティングをもちません。

Command: fundamental-mode: これは、Fundamentalモードにたいするメジャーモードコマンドである。他のモードコマンドと異なり、このモードはカスタマイズしてはならないことになっているので、モードフックは何も実行されない(メジャーモードの慣習を参照)。

メジャーモードを記述するもっとも簡単な方法は、マクロdefine-derived-modeを使用する方法です。これは、既存のメジャーモードを変形して、新たなモードをセットアップします。派生モードの定義を参照してください。define-derived-modeは多くのコーディング規約を自動的に強要するので、たとえ新たなモードが他のモードから明示的に派生されない場合でも、わたしたちはdefine-derived-modeの使用を推奨します。派生元とするための一般的なモードについては、基本的なメジャーモードを参照してください。

標準的なGNU EmacsのLispディレクトリーツリーには、いくつかのメジャーモードがtext-mode.el、texinfo.el、lisp-mode.el、rmail.elのようなファイルとして含まれています。モードの記述方法を確認するために、これらのライブラリーを学ぶことができます。

User Option: major-mode

この変数のバッファーローカル値は、カレントのメジャーモードにたいするシンボルを保持する。この変数のデフォルト値は、新たなバッファーにたいするデフォルトのメジャーモードを保持する。標準的なデフォルト値は、fundamental-modeである。

デフォルト値がnilの場合、C-x b(switch-to-buffer)のようなコマンドを通じてEmacsが新たなバッファーを作成したとき、新たなバッファーは以前カレントだったバッファーのメジャーモードになる。例外として、以前のバッファーのメジャーモードのシンボルプロパティmode-classが値specialをもつ場合、新たなバッファーはFundamentalモードになる(メジャーモードの慣習を参照)。

23.2.1 メジャーモードの慣習		キーマップなどにたいするコーディング規約。
23.2.2 Emacsがメジャーモードを選択する方法		Emacsが自動的にメジャーモードを選択する方法。
23.2.3 メジャーモードでのヘルプ入手		モードの使用方法の探し方。
23.2.4 派生モードの定義		他のメジャーモードにもとづき新たなメジャーモードを定義する。
23.2.5 基本的なメジャーモード		他のモードからよく派生元とされるモード。
23.2.6 モードフック		メジャーモード関数の最後に実行されるフック。
23.2.7 Tabulated Listモード		表形式データを含むバッファーにたいする親モード。
23.2.8 ジェネリックモード		コメント構文とFont Lockモードをサポートするシンプルなメジャーモードの定義。
23.2.9 メジャーモードの例		TextモードとLispモード。

23.2.1 メジャーモードの慣習

メジャーモードにたいするすべてのコードはさまざまなコーディング規約にしたがうべきであり、それらの規約にはローカルキーマップおよび構文テーブルの初期化、関数名や変数名、フックにたいする規約が含まれます。

define-derived-modeマクロを使用した場合は、これらの規約を自動的に配慮します。派生モードの定義を参照してください。Fundamentalモードは、Emacsのデフォルト状態を表すモードなにで、これらの規約が当てはまらないことに注意してください。

以下の規約リストは、ほんの一部です。一般的に、すべてのメジャーモードは、Emacs全体が首尾一貫するよう、他のEmacsメジャーモードとの一貫性を目指すべきです。ここで、この問題を洗い出すすべての想定される要点をリストするのは不可能です。Emacs開発者が、自身の開発するメジャーモードが通常の規約を逸脱する領域を示す場合は、互換性を保つようにしてください。

名前が‘-mode’で終わるようにメジャーモードコマンドを定義する。引数なしで呼び出されたとき、このコマンドはキーマップ、構文テーブル、既存バッファーのバッファーローカル変数をセットアップして、カレントバッファーを新たなモードに切り替えるべきである。そのバッファーのコンテンツを変更するべきではない。
そのモードで利用できる特別なコマンドを説明するドキュメント文字列を記述する。メジャーモードでのヘルプ入手を参照のこと。
そのユーザー自身のキーバインディングに自動的に適合してヘルプが表示されるように、ドキュメント文字列に特別なドキュメントサブストリング‘\[command]’、‘\{keymap}’、‘\<keymap>’を含めるとよいかもしれない。ドキュメント内でのキーバインディングの置き換えを参照のこと。
メジャーモードコマンドは、kill-all-local-variablesを呼び出すことにより開始するべきである。これは、ノーマルフックchange-major-mode-hookを実行してから、前のメジャーモードで効力のあったバッファーローカル変数を解放する。バッファーローカルなバインディングの作成と削除を参照のこと。
メジャーモードコマンドは、変数major-modeにメジャーモードコマンドのシンボルをセットするべきである。これは、describe-modeがプリントするドキュメントを探す手掛かりとなる。
メジャーモードコマンドは、変数mode-nameにそのモードの“愛称(pretty name)”をセットするべきである(これは通常は文字列だが、他の利用可能な形式は、モードラインのデータ構造を参照のこと)。このモード名は、モードラインに表示される。
Calling the major mode command twice in direct succession should not fail and should do the same thing as calling the command only once. In other words, the major mode command should be idempotent.
すべてのグローバル名は同じネームスペースにあるので、モードの一部であるようなすべてのグローバルな変数、定数、関数は、メジャーモード名(メジャーモード名が長いようなら短縮名)で始まる名前をもつべきである。Emacs Lispコーディングの慣習を参照のこと。
プログラム言語のような、ある種の構造型テキストを編集するためのメジャーモードでは、その構造に応じたテキストのインデントはおそらく有用であろう。したがって、そのようなモードはindent-line-functionに適切な関数をセットするとともに、インデント用のその他の変数をカスタマイズすべきだろう。
メジャーモードは通常、そのモードにあるすべてのバッファーのローカルキーマップとして使用される、自モード身のキーマップをもつべきである。メジャーモードコマンドは、そのローカルマップをインストールするために、use-local-mapを呼び出すべきである。詳細は、アクティブなキーマップを参照のこと。
このキーマップは、modename-mode-mapという名前のグローバル変数に永続的に格納されるべきである。通常、そのモードを定義するライブラリーは、この変数をセットする。

モード用のキーマップ変数をセットアップするコードの記述する方法に関するアドバイスは、堅牢な変数定義のためのヒントを参照のこと。
メジャーモードのキーマップ内でバインドされるキーシーケンスは、通常はC-cで始まり、その後にコントロール文字、数字、{、}、<、>、:、;が続くべきである。その他の記号文字(punctuation characters)はマイナーモードに、通常のアルファベット文字はユーザーのために予約されている。
A major mode can also rebind the keys M-n, M-p and M-s. The bindings for M-n and M-p should normally be some kind of moving forward and backward, but this does not necessarily mean cursor motion.

It is legitimate for a major mode to rebind a standard key sequence if it provides a command that does the same job in a way better suited to the text this mode is used for. For example, a major mode for editing a programming language might redefine C-M-a to move to the beginning of a function in a way that works better for that language.

ある標準的なキーシーケンスの標準的な意味が、そのモードではほとんど役に立たないような場合にも、メジャーモードが標準的なキーシーケンスをリバインドする正当性がある。たとえば、ミニバッファーモードは、M-rの標準的な意味はミニバッファーではほとんど使用されないので、このキーシーケンスをリバインドする。テキストの自己挿入を許さないDiredやRmailのようなメジャーモードは、アルファベット文字や、その他のプリント文字を特別なコマンドに再定義する正当性がある。
テキストを編集するメジャーモードは、改行の挿入以外の何かにRETを定義すべきではない。しかし、ユーザーが直接テキストを編集しない、DiredやInfoのような特別なモードにたいしては、完全に異なることを行うようにRETを再定義しても構わない。
メジャーモードは、たとえばAuto-Fillモードを有効にするか等の、主にユーザーの好みに関するオプションを変更すべきではない。それらのオプションは、ユーザーに選択に任せること。ただし、もしユーザーがAuto-Fillモードを使用すると決定した場合には、それが便利に機能するように、他の変数をカスタマイズすべきである。
モードは自身の構文テーブルをもつかもしれず、他の関連するモードと構文テーブルを共有するかもするかもしれない。モードが自身の構文テーブルをもつ場合は、modename-mode-syntax-tableという名前の変数にそれを格納すべきである。構文テーブルを参照のこと。
コメントにたいして構文をもつ言語を扱うモードは、コメント構文を定義する変数をセットすべきである。Options Controlling Comments in The GNU Emacs Manualを参照のこと。
モードは自身のabbrevテーブルをもつかもしれず、他の関連するモードと構文テーブルを共有するかもするかもしれない。モードが自身のabbrevテーブルをもつ場合は、modename-mode-abbrev-tableという名前の変数にそれを格納すべきである。メジャーモードコマンドが自身で何らかのabbrevを定義する場合は、define-abbrevのsystem-flag引数にtを渡すべきである。abbrevの定義を参照のこと。
モードは、変数font-lock-defaultsにバッファーローカルな値をセットすることにより、Font Lockモードにたいしてハイライトする方法を指定すべきである(Font Lockモードを参照)。
モードが定義するすべてのフェイスは、もし可能なら既存のEmacsフェイスを継承すべきである。基本的なフェイスとFont Lockのためのフェイスを参照のこと。
モードは変数imenu-generic-expression、変数imenu-prev-index-position-function and imenu-extract-index-name-function、または変数imenu-create-index-functionにバッファーローカルな値をセットすることにより、Imenuがバッファー内の定義、またはセクションを探す方法を指定すべきである(Imenuを参照)。
モードは、eldoc-documentation-functionにローカル値を指定して、ElDocモードがそのモードを処理する方法を指定できる。
モードは、スペシャルフックcompletion-at-point-functionsに1つ以上のバッファーローカルエントリーを追加することにより、さまざまなキーワードの補完方法を指定できる。通常バッファーでの補完を参照のこと。
Emacsのカスタマイズ変数にたいしてバッファーローカルなバインディングを作成するには、make-variable-buffer-localではなく、メジャーモードコマンド内でmake-local-variableを使用すること。関数、make-variable-buffer-localは、それ以降にカスタマイズ変数をセットするすべてのバッファーにたいしてその変数をローカルにし、そのモードを使用しないバッファーにたいしても影響があるだろう。そのようなグローバルな効果は、モードにとって好ましくない。バッファーローカル変数を参照のこと。
稀な例外として、Lispパッケージ内でmake-variable-buffer-localを使用する唯一の正当な方法は、そのパッケージ内でのみ使用される変数にたいして使用をする場合である。他のパッケージにより使用される変数にたいしてこの関数を使用すると、干渉が起こるだろう。
Each major mode should have a normal mode hook named modename-mode-hook. The very last thing the major mode command should do is to call run-mode-hooks. This runs the normal hook change-major-mode-after-body-hook, the mode hook, the function hack-local-variables (when the buffer is visiting a file), and then the normal hook after-change-major-mode-hook. See section モードフック.
メジャーモードコマンドは、親モード(parent mode)と呼ばれる他のいくつかのメジャーモードを呼び出すことにより開始されるかもしれず、それらのセッティングのいくつかを変更するかもしれない。これを行うモードは、派生モード(derived mode)と呼ばれる。派生モードを定義する推奨方法は、define-derived-modeマクロの使用であるが、これは必須ではない。そのようなモードは、delay-mode-hooksフォーム内で親のモードコマンドを呼び出すべきである(define-derived-modeは自動的にこれを行う)。派生モードの定義、およびモードフックを参照のこと。
ユーザーが、そのモードのバッファーから他のモードのバッファーに切り替える際に特別な何かを行う必要がある場合、モードはchange-major-mode-hookにたいしてバッファーローカル値をセットアップできる(バッファーローカルなバインディングの作成と削除を参照)。
そのモードが、(ユーザーがキーボードでタイプしたテキストや、外部ファイルのテキストではなく)モード自身が生成する特別に用意されたテキストにたいしてのみ適す場合、メジャーモードコマンドのシンボルは、以下のようにmode-classという名前のプロパティに値specialをputすべきである:
```
(put 'funny-mode 'mode-class 'special)
```
これはEmacsにたいして、カレントバッファーがFunnyモードのときに新たなバッファーを作成したとき、たとえmajor-modeのデフォルト値がnilであっても、そのバッファーをFunnyモードにしないよう指示する。デフォルトでは、major-modeにたいする値nilは、新たなバッファー作成時にカレントバッファーのメジャーモードを使用することを意味するが(Emacsがメジャーモードを選択する方法を参照)、specialなモードにたいしてはかわりにFundamentalモードが使用される。Dired、Rmail、Buffer Listのようなモードは、この機能を使用する。

関数view-bufferは、mode-classがspecialであるようなバッファーではViewモードを有効にしない。そのようなモードは、通常は自身でViewに相当するバインディングを提供するからである。

define-derived-modeマクロは、親モードがspecialの場合は、自動的に派生モードをspecialにマークする。親モードでspecialモードが有用なら、それを継承したモードでもであろう。基本的なメジャーモードを参照のこと。
新たなモードを、識別可能な特定のファイルにたいするデフォルトとしたい場合は、そのようなファイル名にたいしてそのモードを選択するために、auto-mode-alistに要素を追加する。autoload用にモードコマンドを定義する場合は、autoloadを呼び出すのと同じファイル内にその要素を追加すべきである。モードコマンドにたいしてautoload cookieを使用する場合は、その要素を追加するフォームにたいしてもautoload cookieを使用できる(autoload cookieを参照)。モードコマンドをautoloadしない場合は、モード定義を含むファイル内で要素を追加すれば十分である。
悪影響を与えることなく1回以上評価されるように、モード定義はファイル内のトップレベルのフォームとして記述すべきである。たとえば、すでに値をもつ変数が再初期化されないように、モードに関連した変数をセットするときは、defvarかdefcustomを使用する(グローバル変数の定義を参照)。

23.2.2 Emacsがメジャーモードを選択する方法

ファイルをvisitするとき、ファイル名やファイル自体の内容などの情報を元に、Emacsはそのバッファーにたいするメジャーモードを選択します。また、ファイルのテキスト内で指定されたローカル変数も処理します。

Command: normal-mode &optional find-file

This function establishes the proper major mode and buffer-local variable bindings for the current buffer. It calls set-auto-mode (see below). As of Emacs 26.1, it no longer runs hack-local-variables, this now being done in run-mode-hooks at the initialization of major modes (see section モードフック).

normal-modeのfind-file引数が非nilの場合、normal-modeはfind-file関数が自身を呼び出したとみなす。この場合、normal-modeはそのファイル内の‘-*-’行の、またはファイルの最後にあるローカル変数を処理するかもしれない。これを行うかどうかは、変数enable-local-variablesが制御する。ファイルのローカル変数セクションの構文は、Local Variables in Files in The GNU Emacs Manualを参照のこと。

インタラクティブにnormal-modeを実行した場合、引数find-fileは通常nilである。この場合、normal-modeは無条件に任意のファイルローカル変数を処理する。

The function calls set-auto-mode to choose and set a major mode. If this does not specify a mode, the buffer stays in the major mode determined by the default value of major-mode (see below).

normal-modeは、メジャーモードコマンド呼び出しの周囲にcondition-caseを使用するので、エラーはcatchされて、‘File mode specification error’とともに、元のエラーメッセージがその後に報告される。

Function: set-auto-mode &optional keep-mode-if-same

This function selects and sets the major mode that is appropriate for the current buffer. It bases its decision (in order of precedence) on the ‘-*-’ line, on any ‘mode:’ local variable near the end of a file, on the ‘#!’ line (using interpreter-mode-alist), on the text at the beginning of the buffer (using magic-mode-alist), and finally on the visited file name (using auto-mode-alist). See How Major Modes are Chosen in The GNU Emacs Manual. If enable-local-variables is nil, set-auto-mode does not check the ‘-*-’ line, or near the end of the file, for any mode tag.

モード特定のためにファイル内容をスキャンするのがふさわしくないファイルタイプがいくつかある。たとえば、tarアーカイブファイルの終わり付近に、特定のファイルにたいしてモードを指定するローカル変数セクションをもつアーカイブメンバーファイルが、たまたま含まれているかもしれない。これは、そのファイルを含むtarファイルに適用されるべきではないだろう。同様に、tiffイメージファイルが、‘-*-’パターンにマッチするように見える行を、最初の行に偶然含むかもしれない。これらの理由により、これらのファイル拡張子はどちらもinhibit-local-variables-regexpsリストのメンバーになっている。Emacsが、(モード指定に限らず)ファイルから任意の種類のローカル変数を検索することを防ぐには、このリストにパターンを追加する。

keep-mode-if-sameが非nilの場合は、すでにそのバッファーが適切なメジャーモードをもつとき、この関数はモードコマンドを呼び出さない。たとえばset-visited-file-nameは、ユーザーがセットしたかもしれないバッファーローカル変数をkillするのを防ぐために、これをtにセットする。

Function: set-buffer-major-mode buffer

この関数は、bufferのメジャーモードを、major-modeのデフォルト値にセットする。major-modeがnilの場合は、(それが適切なら)カレントバッファーのメジャーモードを使用する。例外として、bufferの名前が*scratch*の場合は、モードをinitial-major-modeにセットする。

バッファーを作成する低レベルのプリミティブはこの関数を使用しないが、switch-to-bufferやfind-file-noselectのような中位レベルのコマンドは、バッファーを作成するときは、常にこの関数を使用する。

User Option: initial-major-mode: この変数の値は、*scratch*バッファーの初期のメジャーモードを決定する。値は、メジャーモードコマンドであるようなシンボルであること。デフォルト値はlisp-interaction-modeである。

Variable: interpreter-mode-alist: この変数は、‘#!’行内のコマンドインタープリターを指定するスクリプトにたいして使用するメジャーモードを指定する。変数の値は、(regexp . mode)の形式の要素をもつalistである。これは、そのファイルが\\`regexp\\'にマッチするインタープリターを指定する場合は、modeを使用することを意味する。たとえば、デフォルト要素の1つは("python[0-9.]*" . python-mode)である。

Variable: magic-mode-alist: この変数の値は、(regexp function)という形式の要素をもつalistである。ここで、regexpは正規表現、functionは関数、またはnilである。ファイルをvisitした後に、バッファーの先頭のテキストがregexpにマッチした場合、functionが非nilならset-auto-modeはfunctionを呼び出す。functionがnilの場合は、auto-mode-alistがモードを決定する。

Variable: magic-fallback-mode-alist: これはmagic-mode-alistと同様に機能するが、そのファイルにたいしてauto-mode-alistがモードを指定しない場合だけ処理される点が異なる。

Variable: auto-mode-alist

この変数は、ファイル名パターン(正規表現)と対応するメジャーモードコマンドの連想配列を含む。通常、ファイル名パターンは、‘.el’や‘.c’のようなサフィックスをテストするが、必須ではない。このalistの通常の要素は(regexp . mode-function)のようになる。

たとえば、

(("\\`/tmp/fol/" . text-mode)
 ("\\.texinfo\\'" . texinfo-mode)
 ("\\.texi\\'" . texinfo-mode)

 ("\\.el\\'" . emacs-lisp-mode)
 ("\\.c\\'" . c-mode)
 ("\\.h\\'" . c-mode)
 …)

バージョン番号およびバックアップ用サフィックスをもつファイルをvisitしたとき、それらはfile-name-sans-versions(ファイル名の構成要素を参照)を使用して展開されたファイル名(ファイル名を展開する関数を参照)から取り除かれてregexpとマッチされて、set-auto-modeは対応するmode-functionを呼び出す。この機能により、ほとんどのファイルにたいしてEmacsが適切なメジャーモードを選択することが可能になる。

auto-mode-alistの要素が(regexp function t)という形式の場合は、functionを呼び出した後、Emacsは前回マッチしなかったファイル名部分にたいしてマッチするために、再度auto-mode-alistを検索する。この機能は、圧縮されたパッケージにたいして有用である。("\\.gz\\'" function t)という形式のエントリーは、ファイルを解凍してから、‘.gz’抜きのファイル名にたいして適切なモードに解凍されたファイルを配す。

以下はauto-mode-alistの先頭に、複数のパターンペアーを追加する方法の例である(あなたは、initファイル内でこの種の式を使ったことがあるかもしれない)。

(setq auto-mode-alist
  (append
   ;; ドットで始まる(ディレクトリー名付きの)ファイル名
   '(("/\\.[^/]*\\'" . fundamental-mode)
     ;; ドットのないファイル名
     ("/[^\\./]*\\'" . fundamental-mode)
     ;; ‘.C’で終わるファイル名
     ("\\.C\\'" . c++-mode))
   auto-mode-alist))

23.2.3 メジャーモードでのヘルプ入手

describe-mode関数は、メジャーモードに関する情報を提供します。これは通常、C-h mにバインドされています。この関数は、変数major-mode(メジャーモードを参照)の値を使用します。すべてのメジャーモードがこの変数をセットする必要があるのは、これが理由です。

Command: describe-mode &optional buffer

このコマンドは、カレントバッファーのメジャーモードとマイナーモードのドキュメントを表示する。この関数は、メジャーモードおよびマイナーモードのコマンドのドキュメント文字列を取得するために、documentation関数を使用する(ドキュメント文字列へのアクセスを参照)。

buffer引数に非nilを指定してLispから呼び出された場合、この関数はカレントバッファーではなく、そのバッファーのメジャーモードとマイナーモードのドキュメントを表示する。

23.2.4 派生モードの定義

新しいメジャーモードを定義する推奨された方法は、define-derived-modeを使用して既存のメジャーモードから派生させる方法です。それほど近いモードが存在しない場合はtext-mode、special-mode、またはprog-modeから継承するべきです。基本的なメジャーモードを参照してください。これらがどれも適切でない場合は、fundamental-modeから継承することができます(メジャーモードを参照)。

Macro: define-derived-mode variant parent name docstring keyword-args… body…

このマクロは、variantをメジャーモードコマンドとして定義し、nameをモード名の文字列形式とする。variantとparentは、クォートされていないシンボルであること。

新たなコマンドvariantは、関数parentを呼び出すよう定義され、その後その親モードの特定の性質をオーバーライドする。

新たなモードは、variant-mapという名前の、自身のsparseキーマップ(疎キーマップ)をもつ。define-derived-modeは、variant-mapがすでにセットされていて、かつすでに親をもつ場合を除き、親モードのキーマップを新たなマップの親キーマップにする。
新たなモードは、自身の構文テーブル(syntax table)をもち、それは変数variant-syntax-tableに保持される。ただし、:syntax-tableキーワード(以下参照)を使用して、これをオーバーライドした場合は異なる。define-derived-modeは、variant-syntax-tableがすでにセットされていて、かつ標準的な構文テーブルよ異なる親をもつ場合を除き、ペアレントモードの構文テーブルをvariant-syntax-tableの親とする。
新たなモードは、自身のabbrevテーブル(略語テーブル)をもち、それは変数variant-abbrev-tableに保持される。ただし、:abbrev-tableキーワード(以下参照)を使用して、これをオーバーライドした場合は異なる。
The new mode has its own mode hook, variant-hook. It runs this hook, after running the hooks of its ancestor modes, with run-mode-hooks, as the last thing it does, apart from running any :after-hook form it may have. See section モードフック.

これらに加えて、bodyでparentのその他の性質をオーバーライドする方法を指定できます。コマンドvariantはー、通常のオーバーライドをセットアップした後、そのモードのフックを実行する直前にbody内のフォームを評価します。

parentが非nilのmode-classシンボルプロパティをもつ場合、define-derived-modeはvariantのmode-classプロパティに、同じ値をセットします。これは、たとえばparentがspecialモードの場合は、variantもspecialモードになることを保証します(メジャーモードの慣習を参照)。

parentにたいしてnilを指定することもできます。これにより、新たなモードは親をもたなくなります。その後、define-derived-modeは上述のように振る舞いますが、当然parentにつながるすべてのアクションは省略されます。

引数docstringは、新たなモードにたいするドキュメント文字列を指定します。define-derived-modeは、このドキュメント文字列の最後にそのモードフックに関する一般的な情報と、その後にそのモードのキーマップを追加します。docstringを省略した場合は、define-derived-modeがドキュメント文字列を生成します。

The keyword-args are pairs of keywords and values. The values, except for :after-hook’s, are evaluated. The following keywords are currently supported:

:syntax-table: 新たなモードにたいする構文テーブルを明示的に指定するために、これを使用できる。nil値を指定した場合、新たなモードはparentと同じ構文テーブル、parentもnilの場合は標準的な構文テーブルを使用する(これは、nil値の非キーワード引数は引数を指定しないのと同じという通常の慣習にはしたがわないことに注意されたい)。
:abbrev-table: 新たなモードにたいするabbrevテーブルを明示的に指定するために、これを使用できる。nil値を指定した場合、新たなモードはparentと同じabbrevテーブル、parentもnilの場合は、fundamental-mode-abbrev-tableを使用する(繰り返すが、nil値はこのキーワードを指定しないことではない)。
:group: If this is specified, the value should be the customization group for this mode. (Not all major modes have one.) The command customize-mode uses this. define-derived-mode does not automatically define the specified customization group.
:after-hook: This optional keyword specifies a single Lisp form to evaluate as the final act of the mode function, after the mode hooks have been run. It should not be quoted. Since the form might be evaluated after the mode function has terminated, it should not access any element of the mode function’s local state. An :after-hook form is useful for setting up aspects of the mode which depend on the user’s settings, which in turn may have been changed in a mode hook.

以下は架空の例である:

(defvar hypertext-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map [down-mouse-3] 'do-hyper-link)
    map))

(define-derived-mode hypertext-mode
  text-mode "Hypertext"
  "Major mode for hypertext."
  (setq-local case-fold-search nil))

define-derived-modeが自動的に行うので、この定義内にinteractive指定を記述してはならない。

Function: derived-mode-p &rest modes: この関数は、シンボルmodesで与えられたメジャーモードのいずれかから、カレントメジャーモードが派生された場合は非nilをリターンする。

23.2.5 基本的なメジャーモード

Fundamentalモードは別として、他のメジャーモードの一般的な派生元となるメジャーモードが3つあります。それはTextモード、Progモード、およびSpecialです。Textモードはその本来もつ機能から有用なモードです(たとえば.txtファイルの編集など)。一方、ProgモードとSpecialモードは主にそのようなモード以外のモードの派生元として存在します。

新たなモードは、直接または間接を問わず、可能な限りれら3つのモードから派生させるべきです。その理由の1つは、関連のあるモードファミリー全体(たとえばすべてのプログラミング言語のモード)にたいして、ユーザーが単一のモードフックをカスタマイズできる空からです。

Command: text-mode

Textモードは、人間の言語を編集するためのメジャーモードである。このモードは、文字‘"’および‘\’を区切り文字構文(punctuation syntax: 構文クラスのテーブルを参照)としてもち、M-TABをispell-complete-wordにバインドする(Spelling in The GNU Emacs Manualを参照)。

Textモードから派生されたメジャーモードの例として、HTMLモードがある。SGML and HTML Modes in The GNU Emacs Manualを参照のこと。

Command: prog-mode

Progモードは、プログラミング言語のソースコードを含むバッファーにたいする、基本的なメジャーモードである。Emacsビルトインのプログラミング言語用メジャーモードは、このモードから派生されている。

Progモードは、parse-sexp-ignore-commentsをt(パースにもとづくモーションコマンドを参照)にバインドし、bidi-paragraph-directionをleft-to-right(双方向テキストの表示を参照)にバインドする。

Command: special-mode

Specialモードは、ファイルから直接ではなく、Emacsにより特別(specially)に生成されたテキストを含むバッファーにたいする、基本的なメジャーモードである。Specialモードから派生されたメジャーモードは、mode-classプロパティにspecialーが与えられる(メジャーモードの慣習を参照)。

Specialモードは、バッファーを読み取り専用にセットする。このモードのキーマップは、いくつかの一般的なバインディングを定義し、それにはquit-windowにたいするq、revert-buffer(リバートを参照)にたいするgが含まれる。

Specialから派生されたメジャーモードの例としてはBuffer Menuモードがあり、これは*Buffer List*バッファーにより使用される。Listing Existing Buffers in The GNU Emacs Manualを参照のこと。

これらに加えて、表形式データのバッファーにたいするモードはTabulated Listモードから継承できます。このモードは、Specialモードから順に派生されているモードです。Tabulated Listモードを参照してください。

23.2.6 モードフック

すべてのメジャーモードコマンドは、モード独自のノーマルフックchange-major-mode-after-body-hook、そのモードのモードフック、ノーマルフックafter-change-major-mode-hookを実行することにより終了すべきです。これは、run-mode-hooksを呼び出すことにより行われます。もしそのモードが派生モードなら、自身のbody内で他のメジャーモード(親モード)を呼び出す場合は、親モードが自身でこれらのフックを実行しないように、delay-mode-hooksの中でこれを行うべきです。そのかわりに、派生モードは親のモードフックも実行する、run-mode-hooksを呼び出すのです。メジャーモードの慣習を参照してください。

Emacs 22より前のバージョンのEmacsには、delay-mode-hooksがありません。また、Emacs 24より前のバージョンには、change-major-mode-after-body-hookがありません。ユーザー実装のメジャーモードがrun-mode-hooksを使用せず、これらの新しい機能を使用するようにアップデートされていないときは、これらのメジャーモードは以下の慣習に完全にしたがわないでしょう。それらのモードは、親のモードフックをあまりに早く実行したり、after-change-major-mode-hookの実行に失敗するかもしれません。そのようなメジャーモードに遭遇した場合は、以下の慣習にしたがって修正をお願いします。

When you define a major mode using define-derived-mode, it automatically makes sure these conventions are followed. If you define a major mode “by hand”, not using define-derived-mode, use the following functions to handle these conventions automatically.

Function: run-mode-hooks &rest hookvars

Major modes should run their mode hook using this function. It is similar to run-hooks (see section フック), but it also runs change-major-mode-after-body-hook, hack-local-variables (when the buffer is visiting a file) (see section ファイルローカル変数), and after-change-major-mode-hook. The last thing it does is to evaluate any :after-hook forms declared by parent modes (see section 派生モードの定義).

When this function is called during the execution of a delay-mode-hooks form, it does not run the hooks or hack-local-variables or evaluate the forms immediately. Instead, it arranges for the next call to run-mode-hooks to run them.

Macro: delay-mode-hooks body…

あるメジャーモードコマンドが他のメジャーモードコマンドを呼び出すとき、それはdelay-mode-hooksの内部で行われるべきである。

このマクロはbodyを実行するが、body実行中はすべてのrun-mode-hooks呼び出しにたいして、それらのフックの実行を遅延するよう指示する。それらのフックは、実際にはdelay-mode-hooks構造の最後の後、次のrun-mode-hooks呼び出しの間に実行されるだろう。

Variable: change-major-mode-after-body-hook: これは、run-mode-hooksにより実行されるノーマルフックである。これは、そのモードのフックの前に実行される。

Variable: after-change-major-mode-hook: これは、run-mode-hooksにより実行されるノーマルフックである。これは、すべての適切に記述されたメジャーモードコマンドの一番最後に実行される。

23.2.7 Tabulated Listモード

Tabulated Listモードとは、表形式データ(エントリーから構成されるデータであり、各エントリーはそれぞれテキストの1行を占め、エントリーの内容は列に分割されるようなデータ)を表示するためのメジャーモードです。Tabulated Listモードは、行列の見栄えよくプリントする機能、および各列の値に応じて行をソートする機能を提供します。これは、Specialモードから派生されたモードです(基本的なメジャーモードを参照)。

Tabulated Listモードは、より特化したメジャーモードの親モードとして使用されることを意図しています。例としては、Process Menuモード(プロセスの情報を参照)や、Package Menuモード(Package Menu in The GNU Emacs Manualを参照)が含まれます。

Such a derived mode should use define-derived-mode in the usual way, specifying tabulated-list-mode as the second argument (see section 派生モードの定義). The body of the define-derived-mode form should specify the format of the tabulated data, by assigning values to the variables documented below; optionally, it can then call the function tabulated-list-init-header, which will populate a header with the names of the columns.

派生されたモードは、リスティングコマンドも定義するべきです。これはモードコマンドではなく、(M-x list-processesのように)ユーザーが呼び出すコマンドです。リスティングコマンドは、バッファーを作成または切り替えて、派生モードをオンにして、表形式データを指定し、最後にそのバッファーを事前設定(populate)するためにtabulated-list-printを呼び出すべきです。

Variable: tabulated-list-format

このバッファーローカル変数は、表形式データのフォーマットを指定する。値はベクターで、ベクターの各要素はデータ列を表すリスト(name width sort)である。ここで

nameは列の名前(文字列)。
widthは列にたいして予約される文字数幅(整数)。最終列は各行の終端までなので意味がない。
sortは列によりエントリーをソートする方法を指定する。nilの場合、その列はソートに使用できない。tの場合は、列の文字列値を比較することによりソートされる。それ以外の場合は、tabulated-list-entriesの要素と同じ形式の2つの引数をとる、sortにたいする述語関数(predicate function)であること。

Variable: tabulated-list-entries

このバッファーローカル変数は、Tabulated Listバッファー内に表示されるエントリーを指定する。値にはリスト、または関数のいずれかであること。

値がリストの場合、各リスト要素は1つのエントリーに対応し、(id contents)という形式であること。ここで

id is either nil, or a Lisp object that identifies the entry. If the latter, the cursor stays on the same entry when re-sorting entries. Comparison is done with equal.
contentsは、tabulated-list-formatと要素数が同じベクター。ベクター要素は文字列、またはリスト。文字列の場合は、バッファーにそのまま挿入される。リスト(label . properties)の場合には、labelとpropertiesを引数としてinsert-text-buttonを呼び出すことにより、テキストボタンを挿入することを意味する(ボタンの作成を参照)。
これらの文字列には、改行を含めるべきではない。

それ以外の場合、値は引数なしで呼び出され上記形式のリストをリターンする関数であること。

Variable: tabulated-list-revert-hook: このノーマルフックはTabulated Listバッファーのリバートに先立ち実行される。派生モードは、tabulated-list-entriesを再計算するために、このフックに関数を追加できる。

Variable: tabulated-list-printer: この変数の値は、ポイント位置にエントリー(エントリーを終端する改行を含む)を挿入するために呼び出される関数である。この関数は、tabulated-list-entriesと同じ意味をもつ2つの引数idとcontentsを受け取る。デフォルト値は、エントリーをそのまま挿入する関数である。より複雑な方法によりTabulated Listモードを使用するモードは、別の関数を指定できる。

Variable: tabulated-list-sort-key: この変数の値は、Tabulated Listバッファーにたいするカレントのソートキーを指定する。nilの場合、ソートは行われていない。それ以外では、(name . flip)という形式の値をもつ。ここでnameはtabulated-list-format内の列目の1つとマッチする文字列、flipが非nilの場合は逆順でのソートを意味する。

Function: tabulated-list-init-header

This function computes and sets header-line-format for the Tabulated List buffer (see section ウィンドウのヘッダーライン), and assigns a keymap to the header line to allow sorting entries by clicking on column headers.

Tabulated Listから派生したモードは、上記の変数(特にtabulated-list-formatをセットした後のみ)をセットした後にこれを呼び出すべきである。

Function: tabulated-list-print &optional remember-pos update

この関数は、カレントバッファーにエントリーを準備(populate)する。これはリスティングコマンドとして呼び出されるべきである。この関数は、バッファーを消去してtabulated-list-entriesで指定されるエントリーをtabulated-list-sort-keyにしたがってソートした後、各エントリーを挿入するためにtabulated-list-printerで指定される関数を呼び出す。

オプション引数remember-posが非nilの場合、この関数はカレント行でid要素を探して、もしあればすべてのエントリーを(再)挿入して、その後へそのエントリーの移動を試みる。

If the optional argument update is non-nil, this function will only erase or add entries that have changed since the last print. This is several times faster if most entries haven’t changed since the last time this function was called. The only difference in outcome is that tags placed via tabulated-list-put-tag will not be removed from entries that haven’t changed (normally all tags are removed).

23.2.8 ジェネリックモード

genericモード (generic mode:汎用モード))とは、コメント構文にたいする基本的なサポートとFont Lockモードをもつ、シンプルなメジャーモードです。genericモードを定義するには、マクロdefine-generic-modeを使用します。define-generic-modeの使い方の例は、ファイルgeneric-x.elを参照してください。

Macro: define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring

このマクロは、mode(クォートされていないシンボル)という名前のgenericモードコマンドを定義する。オプション引数docstringは、そのモードコマンドにたいするドキュメント文字列である。これを与えない場合は、define-generic-modeがデフォルトのドキュメント文字列を生成する。

The argument comment-list is a list in which each element is either a character, a string of one or two characters, or a cons cell. A character or a string is set up in the mode’s syntax table as a comment starter. If the entry is a cons cell, the CAR is set up as a comment starter and the CDR as a comment ender. (Use nil for the latter if you want comments to end at the end of the line.) Note that the syntax table mechanism has limitations about what comment starters and enders are actually possible. See section 構文テーブル.

引数keyword-listは、font-lock-keyword-faceでハイライトするキーワードのリストである。キーワードは文字列であること。一方、font-lock-listはハイライトするための追加の式リストである。このリストの各要素は、font-lock-keywordsの要素と同じ形式をもつべきである。検索ベースのフォント化を参照のこと。

引数auto-mode-listは、変数auto-mode-alistに追加する正規表現のリストである。これらの式は、マクロ呼び出しの展開時ではなく、define-generic-modeの実行時に追加される。

最後にfunction-listは、追加セットアップのためにモードコマンドに呼び出される関数のリストである。これらの関数は、モードフック変数mode-hookの実行の直前に呼び出される。

23.2.9 メジャーモードの例

Textモードは、Fundamentalを除き、おそらくもっともシンプルなモードです。上述した慣習の多くを説明するために、以下にtext-mode.elの抜粋を示します:

;; Create the syntax table for this mode.
(defvar text-mode-syntax-table
  (let ((st (make-syntax-table)))
    (modify-syntax-entry ?\" ".   " st)
    (modify-syntax-entry ?\\ ".   " st)
    ;; Add 'p' so M-c on 'hello' leads to 'Hello', not 'hello'.
    (modify-syntax-entry ?' "w p" st)
    st)
  "Syntax table used while in `text-mode'.")


;; このモード用にキーマップを作成

(defvar text-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\e\t" 'ispell-complete-word)
    map)
  "`text-mode'のキーマップ
`mail-mode'、`outline-mode'、`indented-text-mode'のような
他の多くのモードはこのマップ内で定義した全コマンドを継承する")

そして、実際にモードコマンドが定義される方法です:

(define-derived-mode text-mode nil "Text"
  "人間が読むために記述されたテキストを編集するためのメジャーモード
このモードではパラグラフを区切るのはブランク行か空白行だけである
したがって適応型フィル(adaptive filling)の全恩恵を受けられる
 (変数`adaptive-fill-mode'を参照のこと)
\\{text-mode-map}
Textモードのオンによりノーマルフック`text-mode-hook'が実行される"

  (set (make-local-variable 'text-mode-variant) t)
  (set (make-local-variable 'require-final-newline)
       mode-require-final-newline)
  (set (make-local-variable 'indent-line-function) 'indent-relative))

(indent-relativeがデフォルト値の現在では、最後の行は冗長なので、将来のバージョンで削除するつもりです。)

3つのLisp用モード(Lispモード、Emacs Lispモード、Lisp Interactionモード)は、Textモードより多くの機能をもち、それにふさわしくコードもより複雑です。そのようなモードの記述方法を説明するために、lisp-mode.elの抜粋を示します。

以下は、Lispモードの構文テーブルとabbrevテーブルを定義する方法です:

;; モード固有のテーブル変数の作成
(defvar lisp-mode-abbrev-table nil)
(define-abbrev-table 'lisp-mode-abbrev-table ())

(defvar lisp-mode-syntax-table
  (let ((table (copy-syntax-table emacs-lisp-mode-syntax-table)))
    (modify-syntax-entry ?\[ "_   " table)
    (modify-syntax-entry ?\] "_   " table)
    (modify-syntax-entry ?# "' 14" table)
    (modify-syntax-entry ?| "\" 23bn" table)
    table)
  "`lisp-mode'で使用される構文テーブル")

Lisp用の3つのモードは、コードの多くを共有します。たとえば、以下の関数呼び出しにより、さまざまな変数がセットされます:

(defun lisp-mode-variables (&optional syntax keywords-case-insensitive)
  (when syntax
    (set-syntax-table lisp-mode-syntax-table))
  (setq local-abbrev-table lisp-mode-abbrev-table)
  …

その中でも特に、以下の関数はLispコメントを処理するために、変数comment-startをセットアップします:

  (make-local-variable 'comment-start)
  (setq comment-start ";")
  …

これら異なるLisp用モードは、微妙に異なるキーマップをもちます。たとえば、LispモードはC-c C-zをrun-lispにバインドしますが、他のLisp用モードはこれを行いません。とはいえ、すべてのLisp用モードに共通なコマンドがいくつかあります。以下のコードは、それらの共通コマンドをセットアップします:

(defvar lisp-mode-shared-map
  (let ((map (make-sparse-keymap)))
    (define-key map "\e\C-q" 'indent-sexp)
    (define-key map "\177" 'backward-delete-char-untabify)
    map)
  "すべてのLisp用モードでコマンドを共有するためのキーマップ")

そして、以下がLispモードのためのキーマップをセットアップするコードです:

(defvar lisp-mode-map
  (let ((map (make-sparse-keymap))
	(menu-map (make-sparse-keymap "Lisp")))
    (set-keymap-parent map lisp-mode-shared-map)
    (define-key map "\e\C-x" 'lisp-eval-defun)
    (define-key map "\C-c\C-z" 'run-lisp)
    …
    map)
  "Keymap for ordinary Lisp mode.
All commands in `lisp-mode-shared-map' are inherited by this map.")

最後は、Lispモードのためのメジャーモードコマンドです:

(define-derived-mode lisp-mode prog-mode "Lisp"
  "GNU Emacs Lisp以外のLispコードを編集するためのメジャーモード
コマンド:
後方に移動させるかのようにタブをスペースに削除変換する。
パラグラフ区切りはブランク行。コメント開始はセミコロン。

\\{lisp-mode-map}
`run-lisp'はinferior Lispジョブの開始と既存ジョブ
から戻るための両方に使われるかもしれないことに注意

このモードへのエントリーにより、
`lisp-mode-hook'の値が非nilならそれを呼び出す"
  (lisp-mode-variables nil t)
  (set (make-local-variable 'find-tag-default-function)
       'lisp-find-tag-default)
  (set (make-local-variable 'comment-start-skip)
       "\\(\\(^\\|[^\\\\\n]\\)\\(\\\\\\\\\\)*\\)\\(;+\\|#|\\) *")
  (setq imenu-case-fold-search t))

23.3 マイナーモード

マイナーモード(minor mode)は、メジャーモードの選択とは無関係にユーザーが有効、あるいは無効にする可能性のある、オプション機能を使用を提供します。マイナーモードは個別に、あるいは組み合わせて有効にできます。

ほとんどのマイナーモードは、メジャーモードとは独立した機能を実装し、それゆえにほとんどのメジャーモードとともに使用することができます。たとえば、Auto Fillモードはテキスト挿入を許す任意のメジャーモードとともに機能します。しかし少数ながら、特定のメジャーモードに特化した少数のマイナーモードもあります。たとえば、Diff Auto Refineモードは、Diffモードとともに使用されることだけを意図したマイナーモードです。

理想的には、マイナーモードは他のマイナーモードの効果と無関係に、期待する効果をもつべきです。これは、任意の順序でマイナーモードをアクティブ、あるいは非アクティブにしても可能なはずです。

Variable: minor-mode-list: この変数の値は、すべてのマイナーモードコマンドのリストである。

23.3.1 マイナーモード記述の規約

メジャーモードにあるように、マイナーモードの記述にも慣習があります。以下で、その慣習について説明します。これらの慣習にしたがうには、マクロdefine-minor-modeを使用するのがもっとも簡単な方法です。マイナーモードの定義を参照してください。

名前が‘-mode’で終わる変数を定義する。これをモード変数(mode variable)と呼ぶ。マイナーモードコマンドは、この変数をセットすべきである。値は、そのモードが無効な場合はnil、有効な場合は非nilになるだろう。そのマイナーモードがバッファーローカルなら、この変数もバッファーローカルであること。
この変数は、モードラインにマイナーモードの名前を表示するために、minor-mode-alistと結合して使用される。これは、minor-mode-map-alistを通じて、そのマイナーモードのキーマップがアクティブかどうかも判定する(アクティブなキーマップの制御を参照)。個々のコマンドやフックも、この変数の値をチェックできる。
モード変数と同じ名前をもつ、モードコマンド(mode command)と呼ばれるコマンドを定義する。このコマンドの役目は、モード変数の値のセットに加えて、そのモードの機能を使用を実際に有効、または無効にするために必要な、その他すべてを行うことである。
モードコマンドは、1つのオプション引数を受け入れるべきである。プレフィクス引数なしでinteractiveに呼び出された場合は、モードをトグルする(toggle: 切り替える。たとえば無効なら有効に、有効なら無効にする)こと。プレフィクス引数とともにinteractiveに呼び出された場合、その引数が正であればモードを有効に、それ以外は無効にすべきである。

モードコマンドが、Lispから(つまりからの非interactiveに)呼び出された場合は、引数が省略、またはnilの場合はモードを有効にすべきである。引数がシンボルtoggleの場合はモードをトグルし、それ以外の場合は、上述の数引数とともにinteractiveに呼び出されたときと同じ方法により、その引数を扱うべきである。

以下は、この挙動の実装方法を示す例である(define-minor-modeマクロが生成するコードも、これに類似する)。
```
(interactive (list (or current-prefix-arg 'toggle)))
(let ((enable
       (if (eq arg 'toggle)
           (not foo-mode) ; this is the mode’s mode variable
         (> (prefix-numeric-value arg) 0))))
  (if enable
      do-enable
    do-disable))
```
この、やや複雑な挙動の理由は、ユーザーが簡単かつinteractiveにマイナーモードをトグルでき、以下のようにモードフック内で簡単にマイナーモードを有効にできるからである:
```
(add-hook 'text-mode-hook 'foo-mode)
```
foo-modeモードコマンドは、引数なしでLispから呼び出されたときは、無条件にそのマイナーモードを有効にするので、これはfoo-modeがすでに有効でもそうでなくても正しく振る舞う。モードフック内でマイナーモードを無効にする場合は、少々醜くなる:
```
(add-hook 'text-mode-hook (lambda () (foo-mode -1)))
```
しかし、これは頻繁には行われない。

Enabling or disabling a minor mode twice in direct succession should not fail and should do the same thing as enabling or disabling it only once. In other words, the minor mode command should be idempotent.
モードラインにマイナーモードを標示したい場合は、それぞれのマイナーモードにたいして、要素をminor-mode-alistに追加する(Definition of minor-mode-alistを参照)。この要素は以下の形式のリストであること:
```
(mode-variable string)
```
ここで、mode-variableはマイナーモードの有効化を制御する変数であり、stringはモードラインに標示するための、スペースで始まる短い文字列である。一度に複数モードの文字列がスペースを占めるので、これらの文字列は短くなければならない。

minor-mode-alistに要素を追加する際は、重複を避けるために、既存要素のチェックにassqを使用すること。たとえば:
```
(unless (assq 'leif-mode minor-mode-alist)
  (push '(leif-mode " Leif") minor-mode-alist))
```
または、以下のようにadd-to-list(リスト変数の変更を参照)を使用すること:
```
(add-to-list 'minor-mode-alist '(leif-mode " Leif"))
```

これらに加えて、メジャーモードにたいする慣習のいくつかは、マイナーモードにたいしても同様に適用されます。それらの慣習はグローバルシンボルの名前、初期化関数の最後でのフックの使用、キーマップおよびその他のテーブルの使用です。

マイナーモードは、可能ならばCustom(カスタマイズ設定を参照)を通じての有効化および無効化をサポートするべきです。これを行うには、モード変数はは通常は:type 'booleanとともにdefcustomで定義されるべきです。その変数をセットするだけではモードの有効化に不足なら、モードコマンドを呼び出すことによりモードを有効にする:setメソッドも指定するべきです。そして、その変数のドキュメント文字列にCustomを通じて変数をセットしなければ効果がないことを注記してください。さらに、その定義をautoload cookie(autoload cookieを参照)でマークして、その変数のカスタマイズによりモードを定義するライブラリーがロードされるように:requireを指定します。たとえば:

;;;###autoload
(defcustom msb-mode nil
  "msb-modeをトグルする
この変数を直接セットしても効果がない
\\[customize]か関数`msb-mode'を使用すること"
  :set 'custom-set-minor-mode
  :initialize 'custom-initialize-default
  :version "20.4"
  :type    'boolean
  :group   'msb
  :require 'msb)

23.3.2 キーマップとマイナーモード

マイナーモードはそれぞれ自身のキーマップをもつことができ、そのモードが有効になるとそのキーマップがアクティブになります。マイナーモード用のキーマップをセットアップするには、minor-mode-map-alistというalistに要素を追加します。Definition of minor-mode-map-alistを参照してください。

One use of minor mode keymaps is to modify the behavior of certain self-inserting characters so that they do something else as well as self-insert. (Another way to customize self-insert-command is through post-self-insert-hook, see ユーザーレベルの挿入コマンド. Apart from this, the facilities for customizing self-insert-command are limited to special cases, designed for abbrevs and Auto Fill mode. Do not try substituting your own definition of self-insert-command for the standard one. The editor command loop handles this function specially.)

マイナーモードは、コマンドをC-cとその後の区切り文字より構成されるキーシーケンスにバインドするかもしれません。しかし、C-cとその後の{}<>:;のいずれかの文字、またはコントロール文字、数字より構成されるシーケンスは、メジャーモード用に予約されています。また、C-c letterはユーザー用に予約されています。キーバインディングの慣習を参照してください。

23.3.3 マイナーモードの定義

マクロdefine-minor-modeは、1つの自己完結した定義内にモードを実装する便利な方法を提供します。

Macro: define-minor-mode mode doc [init-value [lighter [keymap]]] keyword-args… body…

このマクロは、名前がmode(シンボル)の新たなマイナーモードを定義する。これは、ドキュメント文字列としてdocをもつ、マイナーモードをトグルするための、modeという名前のコマンドを定義する。

トグルコマンドは１つのオプション(プレフィクス)引数をとる。引数なしでinteractiveに呼び出された場合は、そのモードのオンとオフをトグルする。正のプレフィクス引数はモードを有効にし、それ以外のプレフィクス引数はモードを無効にする。Lispから呼び出した場合、引数がtoggleの場合はモードをトグルし、引数が省略もしくはnilの場合はモードを有効にする。これはたとえば、メジャーモードフック内でマイナーモードを有効にするのを簡便にする。docがnilの場合、このマクロは上記を説明するデフォルトのドキュメント文字列を提供する。

デフォルトでは、これはモードを有効にするとt、無効にするとnilにセットされる、modeという名前の変数も定義する。この変数は、init-valueに初期化される。通常では(以下参照)、この値はnilでなければならない。

文字列lighterは、モード有効時にモードライン内に何を表示するか指定する。これがnilの場合は、このモードはモードライン内に表示されない。

オプション引数keymapは、そのマイナーモードにたいするキーマップを指定する。非nilの場合、それは(値がキーマップであるような)変数の名前、キーマップ、または以下の形式のalistであること

(key-sequence . definition)

ここで、それぞれのkey-sequenceとdefinitionは、define-keyに渡すのに適した引数である(キーバインディングの変更を参照)。keymapはキーマップまたはalistであり、これは変数mode-mapも定義する。

上記の3つの引数init-value、lighter、keymapは、keyword-argsが使用されたときは、(部分的に)省略できる。keyword-argsは、キーワードとその後の対応する値により構成され、いくつかのキーワードは特別な意味をもつ:

:group group

生成されるすべてのdefcustomフォームで使用されるカスタムグループ名。mode(後の‘-mode’がある場合はそれを除く)にたいするデフォルトである。警告: そのグループを定義するためdefgroupを正しく記述していない場合は、このデフォルトグループ名を使用してはならない。カスタマイズグループの定義を参照のこと。

:global global

非nilの場合、これはそのマイナーモードがバッファーローカルでなくグローバルであることを指定する。デフォルトはnil。

マイナーモードをグローバルにしたときの効果の1つは、mode変数がカスタマイズ変数になることである。Customizeインターフェイスを通じてこの変数をトグルするとモードがオン、またはオフになり、変数の値は将来のEmacsセッション用に保存できるようになる(Saving Customizations in The GNU Emacs Manualを参照)。保存された変数が機能するためには、Emacsが開始されるたびにdefine-minor-modeフォームが確実に評価されるようにすべきである。Emacsの一部ではないパッケージにたいしては、:requireキーワードを指定するのが、これを行う一番簡単な方法である。

:init-value init-value

これは、init-value引数を指定するのと等しい。

:lighter lighter

これは、lighter引数を指定するのと等しい。

:keymap keymap

これは、keymap引数を指定するのと等しい。

:variable place

これは、そのモードの状態を格納するために使用される、デフォルトの変数modeを置き換える。これを指定した場合、mode変数は定義されず、すべてのinit-value引数は使用されない。placeは異なる名前の変数(あなた自身が定義しなければならない)、またはsetf関数とともに使用され得るすべてのもの(ジェネリック変数を参照)。placeにはコンス(get . set)も指定できる。ここで、getはカレント状態をリターンする式であり、setはそれをセットする1つの引数(状態)をとる関数である。

:after-hook after-hook

これは、モードフック実行後に評価される、単一のLispフォームを定義する。これはクォートすべきでない。

その他のすべてのキーワード引数は、変数modeにたいして生成されたdefcustomに直接渡される。

modeという名前のコマンドは、最初にmodeという名前の変数をセットする等の標準的な動作を処理した後に、もしあればbodyフォームを実行する。それからモードフック変数mode-hookを実行し、:after-hook内のフォームを評価して終了する。

init-valueの値はnilでなければなりません。ただし、(1)Emacsによりそのモードが事前ロードされている、または(2)たとえユーザーが要求しなくともモードを有効にするためにロードするのが容易な場合を除きます。たとえば、他の何かが有効でなければそのモードの効果がなく、常にそのタイミングでロードされるような場合は、デフォルトでそのモードを有効にすることに害はありません。しかし、この状況は通常はあり得ません。通常は、init-valueの値はnilでなければならないのです。

easy-mmode-define-minor-modeという名前は、このマクロにたいするエイリアスです。

以下は、define-minor-modeの使い方の例です:

(define-minor-mode hungry-mode
  "Hungryモードをトグルする。
引数なしでinteractiveに呼び出すとモードをトグルする。
正のプレフィクス引数でモードを有効に、その他のプレフィクス引数で
無効にする。Lispから呼び出す場合、引数を省略、またはnilなら
モードを有効に、`toggle'なら状態をトグルする。

Hungryモードが有効なときは、C-DELキーは、
最後を除く先行するすべての空白を飲み込む。
コマンド \\[hungry-electric-delete] を参照のこと。"
 ;; 初期値
 nil
 ;; モードラインの標示
 " Hungry"
 ;; マイナーモードのバインディング
 '(([C-backspace] . hungry-electric-delete))
 :group 'hunger)

これは、“Hungry mode”という名前のマイナーモード、モードをトグルするhungry-modeという名前のコマンド、モードが有効かどうかを示すhungry-modeという名前の変数、モードが有効なときそのキーマップを保持するhungry-mode-mapという名前の変数を定義します。これは、C-DELにたいするキーバインディングでキーマップを初期化します。また、変数hungry-modeをカスタムグループhungerに置きます。bodyフォームはありません — 多くのマイナーモードは必要としません。

以下は、これを記述する等価な方法です:

(define-minor-mode hungry-mode
  "Hungryモードをトグルする。
...省略..."
 ;; 初期値
 :init-value nil
 ;; モードラインへのインジケーター
 :lighter " Hungry"
 ;; マイナーモードのバインディング
 :keymap
 '(([C-backspace] . hungry-electric-delete)
   ([C-M-backspace]
    . (lambda ()
        (interactive)
        (hungry-electric-delete t))))
 :group 'hunger)

Macro: define-globalized-minor-mode global-mode mode turn-on keyword-args…

これは、global-modeという名前をグローバルにトグルする。この意味は、modeという名前のバッファーローカルなマイナーモードを、すべてのバッファーで有効、または無効にするということである。あるバッファー内でそのマイナーモードをオンにするには、関数turn-onを使用する。マイナーモードをオフにするには、-1を引数としてmodeを呼び出す。

モードをグローバルに有効にすると、それ以降ファイルをvisitすることにより作成されるバッファー、Fundamental以外のメジャーモードを使用するバッファーにも影響がある。しかし、Fundamentalで作成される新たなバッファーは検知しない。

これは、Customizeインターフェイス内でそのマイナーモードのオン/オフを切り替える、カスタムオプションglobal-mode(カスタマイズ設定)を定義する。define-minor-modeと同様に、たとえば:requireを与える等により、毎回のEmacs開始時に確実にdefine-globalized-minor-modeフォームが評価されるようにすべきである。

グローバルマイナーモードのモード変数にたいしてカスタムグループを指定するには、keyword-args内で:group groupを使用する。

一般的には、グローバル化されたマイナーモードを定義するときは、ユーザーがバッファーごとにモードを使用(または無効に)できるように、非グローバル版も定義すべきである。ことにより、特定のメジャーモード内でそのモードのフックを使用することにより、グローバル有効化されたマイナーモードを無効にすることができるようになる。

23.4 モードラインのフォーマット

Emacsの各ウィンドウ(ミニバッファーウィンドウを除く)には通常、最下部にモードラインがあり、そのウィンドウ内に表示されたバッファーについてステータス情報がモードラインに表示されます。モードラインには、バッファー名、関連するファイル、再帰編集の深さ、およびメジャーモードやマイナーモードなどのような、そのバッファーに関する情報が含まれています。ウィンドウはヘッダーライン(header line)をもつこともでき、これはモードラインによく似ていますが、ウィンドウの最上部に表示されます。

このセクションでは、モードラインおよびヘッダーラインのコンテンツの制御の仕方について説明します。このチャプターにモードラインを含めた理由は、モードラインに表示される情報の多くが、有効化されたメジャーモードとマイナーモードに関係があるからです。

23.4.1 モードラインの基礎		モードライン制御の基本概念。
23.4.2 モードラインのデータ構造		モードラインを制御するデータ構造。
23.4.3 モードライン制御のトップレベル		トップレベル変数、mode-line-format。
23.4.4 モードラインで使用される変数		そのデータ構造で使用される変数。
23.4.5 モードラインでの`%`構造		モードラインへの情報の配置。
23.4.6 モードラインでのプロパティ		モードライン内でのテキストプロパティの使用。
23.4.7 ウィンドウのヘッダーライン		モードラインに類似した最上部のライン。
23.4.8 モードラインのフォーマットのエミュレート		モードラインのようにテキストをフォーマットする。

23.4.1 モードラインの基礎

The contents of each mode line are specified by the buffer-local variable mode-line-format (see section モードライン制御のトップレベル). This variable holds a mode line construct: a template that controls what is displayed on the buffer’s mode line. The value of header-line-format specifies the buffer’s header line in the same way. All windows for the same buffer use the same mode-line-format and header-line-format unless a mode-line-format or header-line-format parameter has been specified for that window (see section ウィンドウのパラメーター).

効率的な理由により、Emacsは各ウィンドウのモードラインとヘッダーラインを、連続して再評価しません。たとえばウィンドウ設定(window configuration)の変更、バッファーの切り替え、バッファーのナローイング(narrowing)またはワイドニング(widening)、スクロール、バッファーの変更等、それを呼び出す状況が出現したときに、Emacsは再評価を行います。mode-line-formatやheader-line-format(モードラインで使用される変数を参照)により参照される任意の変数、またはテキストが表示される方法に影響を与えるデータ構造(Emacsのディスプレー表示を参照)を変更した場合は、表示を更新するために関数force-mode-line-updateを使用するべきです。

Function: force-mode-line-update &optional all

この関数は、次の再表示サイクルの間に、すべての関連する変数の最新の値にもとづき、カレントバッファーのモードラインとヘッダーラインの更新をEmacsに強制する。オプション引数allが非nilの場合は、すべてのモードラインとヘッダーラインの更新を強制する。

この関数は、メニューバーとフレームタイトルの更新も強制する。

選択されたウィンドウのモードラインは、通常はフェイスmode-lineを使用して異なるカラーで表示されます。かわりに、他のウィンドウのモードラインは、フェイスmode-line-inactiveで表示されます。フェイスを参照してください。

23.4.2 モードラインのデータ構造

モードラインのコンテンツは、モードライン構成(mode line construct)と呼ばれるデータ構造により制御されます。モードライン構成はリスト、シンボル、数字を保持するバッファーローカル変数により構成されます。それぞれのデータ型は、以下で説明するようにモードラインの外見にたいして特別な意味をもちます。フレームタイトル(フレームのタイトルを参照)とヘッダーライン(ウィンドウのヘッダーラインを参照)にたいしても、同じデータ構造が使用されます。

固定文字列のようにシンプルなモードライン構成の場合もありますが、通常はモードライン構成のテキストを構築するために、固定文字列と変数の値を組み合わせる方法を指定します。これらの変数の多くは、その変数自体がその値によりモードライン構成を定義する変数です。

以下は、モードライン構成における、さまざまなデータ型の意味です:

string

モードライン構成においての文字列は、文字列内に%構成(%-constructs)を含む以外は、そのまま表現される。これらは、他のデータによる置換を意味する。モードラインでの%構造を参照のこと。

文字列の一部がfaceプロパティをもつ場合は、バッファー内でそれらが表示されるときと同じように、テキスト表示を制御する。faceプロパティをもたない文字は、デフォルトのフェイスmode-line、またはmode-line-inactiveで表示される(Standard Faces in The GNU Emacs Manualを参照)。string内のhelp-echoプロパティとkeymapプロパティは、特別な意味をもつ。モードラインでのプロパティを参照のこと。

symbol

モードライン構成においてのシンボルは、その値を意味する。モードライン構成としては、symbolの値はsymbolの位置に使用される。しかし、シンボルtとnilは、値がvoidであるようなシンボルとして無視される。

例外が1つある。symbolの値が文字列の場合、それはそのまま表示され、%構成は認識されない。

Unless symbol is marked as risky (i.e., it has a non-nil risky-local-variable property), all text properties specified in symbol’s value are ignored. This includes the text properties of strings in symbol’s value, as well as all :eval and :propertize forms in it. (The reason for this is security: non-risky variables could be set automatically from file variables without prompting the user.)

(string rest…)

(list rest…)

最初の要素が文字列またはリストであるようなリストは、すべての要素を再帰的に処理して、その結果を結合することを意味する。これは、モードライン構成において、もっとも一般的なフォームである。

(:eval form)

最初の要素がシンボル:evalであるようなリストは、formを評価して、その結果を表示する文字列として使用するよう指示する。この評価がファイルをロードできないことを確認すること。ファイルをロードすると、無限再帰が発生するかもしれない。

(:propertize elt props…)

最初の要素がシンボル:propertizeであるようなリストは、モードライン構成eltを再帰的に処理して、propsにより指定されるテキストプロパティに結果を加えるよう指示する。引数propsは、0個以上のtext-propertyとvalueのペアーで構成されるべきである。

(symbol then else)

最初の要素がキーワード以外のシンボルであるようなリストは、条件文を指定する。その意味は、symbolの値に依存する。symbolが非nil値をもつ場合は、モードライン構成として、2つ目の要素thenが再帰的に処理され、それ以外は3つ目の要素elseが再帰的に処理される。elseは省略でき、その場合symbolの値がnilかvoidならば、モードライン構成は何も表示しない。

(width rest…)

最初の要素が整数であるようなリストは、restの結果の切り詰め、またはパディングを指定する。残りの要素restは、モードライン構成として再帰的に処理され、互いに結合される。widthが正の場合、結果の幅がwidthより少ないときは、右側にスペースがパディングされる。widthが負の場合、結果の幅が-widthより大きいときは、右側が切り詰められる。

たとえば、ウィンドウ最上部からのバッファー位置をパーセント表示するには、(-3 "%p")のようなリストを使用すればよい。

23.4.3 モードライン制御のトップレベル

変数mode-line-formatは、モードラインの全体的な制御を行います。

User Option: mode-line-format

この変数の値は、モードラインのコンテンツを制御するモードライン構成である。これは、すべてのバッファーにおいて、常にバッファーローカルである。

あるバッファー内でこの変数にnilをセットした場合、そのバッファーはモードラインをもたない(高さが1行しかないウィンドウも、モードラインを表示しない)。

mode-line-formatのデフォルト値は、mode-line-positionやmode-line-modes(これはmode-nameとminor-mode-alistの値を組み込む)のような、他の変数の値を使用するようデザインされています。mode-line-format自体を変更する必要があるモードは、ほとんどありません。ほとんどの用途にたいしては、mode-line-formatが直接、または間接的に参照する、いくつかの変数を修正すれば十分です。

mode-line-formatl自体の変更を行った場合、新たな値は他の様式でコンテンツを複製したり情報を表示するのではなく、デフォルト値(モードラインで使用される変数を参照)に現れるのと同じ変数を使用するべきです。この方法を使用すれば、ユーザーや(display-timeやメジャーモードのような)Lispプログラムにより行われたカスタマイズは、それらの変数への変更を通じて、効力を保ちます。

以下は、Shellモードにたいして有用かもしれない、架空のmode-line-formatの例です(実際には、Shellモードはmode-line-formatをセットしない):

(setq mode-line-format
  (list "-"
   'mode-line-mule-info
   'mode-line-modified
   'mode-line-frame-identification
   "%b--"

   ;; これはリスト作成中に評価されることに注意。
   ;; これは単なる文字列のモードライン構成を作成する。
   (getenv "HOST")

   ":"
   'default-directory
   "   "
   'global-mode-string
   "   %[("
   '(:eval (mode-line-mode-name))
   'mode-line-process
   'minor-mode-alist
   "%n"
   ")%]--"

   '(which-func-mode ("" which-func-format "--"))
   '(line-number-mode "L%l--")
   '(column-number-mode "C%c--")
   '(-3 "%p")))

(変数line-number-mode、column-number-mode、which-func-modeは特定のマイナーモードを有効にする。通例どおり、これらの変数名は、マイナーモードコマンド名でもある。)

23.4.4 モードラインで使用される変数

This section describes variables incorporated by the standard value of mode-line-format into the text of the mode line. There is nothing inherently special about these variables; any other variables could have the same effects on the mode line if the value of mode-line-format is changed to use them. However, various parts of Emacs set these variables on the understanding that they will control parts of the mode line; therefore, practically speaking, it is essential for the mode line to use them. Also see Optional Mode Line in The GNU Emacs Manual.

Variable: mode-line-mule-info: この変数は、言語環境(language environment)、バッファーコーディングシステム、カレント入力メソッド(current input method)に関する情報のモードライン構成の値を保持する。非ASCII文字を参照のこと。

Variable: mode-line-modified

この変数は、カレントバッファーが変更されたかどうかを表示する、モードライン構成の値を保持する。デフォルト値ではバッファーが変更されていれば‘**’、バッファーが変更されていなければ‘--’、バッファーが読み取り専用なら‘%%’、読み取り専用だが変更されているときは‘%*’を表示する。

この変数を変更しても、モードラインは強制的に更新されない。

Variable: mode-line-frame-identification: この変数は、カレントフレームを識別する。デフォルト値では、複製フレームを表示可能なウィンドウシステムを使用している場合は" "、一度に1つのフレームだけを表示する通常の端末では"-%F "を表示する。

Variable: mode-line-buffer-identification: この変数は、そのウィンドウ内で表示されているバッファーを識別する。デフォルト値では、少なくとも12列になるようスペースパディングされたバッファー名を表示する。

Variable: mode-line-position: この変数は、バッファー内での位置を標示する。デフォルト値ではバッファーのパーセントを表示し、オプションでバッファーサイズ、行番号、列番号を表示する。

User Option: mode-line-percent-position: This option is used in mode-line-position. Its value specifies both the buffer percentage to display (one of nil, "%o", "%p", "%P" or "%q", see section モードラインでの%構造) and a width to space-fill or truncate to. You are recommended to set this option with the customize-variable facility.

Variable: vc-mode: 変数vc-modeは、各バッファーにたいしてバッファーローカルであり、そのバッファーがvisitしているファイルがバージョンコントロールで保守されているかどうかと、保守されている場合はバージョンコントロールシステムの種別を表示する。新しいモードラインに表示される文字列、バージョンコントロールされていない場合はnilである。

Variable: mode-line-modes: この変数は、そのバッファーのメジャーモードとマイナーモードを表示する。デフォルト値では再帰編集レベル(recursive editing level)、プロセス状態の情報、ナローイング(narrowing)効果の有無を表示する。

Variable: mode-line-remote: この変数は、カレントバッファーにたいするdefault-directoryがリモートかどうかを表示するために使用される。

Variable: mode-line-client: この変数は、emacsclientフレームを識別するために使用される。

以下の3つの変数は、mode-line-modes内で使用されます:

Variable: mode-name: このバッファーローカル変数は、カレントバッファーのメジャーモードの“愛称(pretty name)”を保持する。モード名がモードラインに表示されるように、それぞれのメジャーモードは、この変数をセットすべきである。値は文字列である必要はなく、モードライン構成内で有効な任意のデータ型(モードラインのデータ構造を参照)を使用できる。モードライン内でモード名を識別する文字列の計算には、format-mode-lineを使用する(モードラインのフォーマットのエミュレートを参照)。

Variable: mode-line-process: このバッファーローカル変数には、そのモードにおいて、サブプロセスとの通信にたいするプロセス状態のモードライン情報が含まれる。これはメジャーモード名の直後(間のスペースはない)に表示される。たとえば、*shell*バッファーでの値は(":%s")であり、これは‘(Shell:run)’のように、メジャーモードとともにその状態を表示する。通常、この変数はnilである。

Variable: mode-line-front-space: This variable is displayed at the front of the mode line. By default, this construct is displayed right at the beginning of the mode line, except that if there is a memory-full message, it is displayed first.

Variable: mode-line-end-spaces: This variable is displayed at the end of the mode line.

Variable: mode-line-misc-info: Mode line construct for miscellaneous information. By default, this shows the information specified by global-mode-string.

Variable: minor-mode-alist

この変数は、マイナーモードがアクティブかをモードラインに示す方法を指定する要素をもつ、連想リスト(association list)を保持する。minor-mode-alistの各要素は、2要素のリストであること:

(minor-mode-variable mode-line-string)

より一般的には、mode-line-stringは任意のモードライン構成であり得る。minor-mode-variableの値が非nilの場合はモードラインに表示され、それ以外では表示されない。一緒に実行されないよう、これらの文字列はスペースで始まるべきである。慣例的に、特定のモードにたいするminor-mode-variableは、そのマイナーモードがアクティブになった際には、非nil値にセットされる。

minor-mode-alist自体はバッファーローカルではない。このalist内で参照される各変数は、そのマイナーモードをバッファーごとに個別に有効にできる場合は、バッファーローカルであること。

Variable: global-mode-string

この変数は、モードライン内でマイナーモードwhich-func-modeがセットされている場合はその直後、セットされていなければmode-line-modesの後に表示されるモードライン構成を保持する(デフォルト)。コマンドdisplay-timeは、時間とロードの情報を含む文字列を保持する変数display-time-stringを参照する、global-mode-stringをセットする。

‘%M’構成は、global-mode-stringの値を置き換えるが、この変数はmode-line-formatからモードラインにincludeされるので、時代遅れである。

以下は、mode-line-formatのデフォルト値の簡略化バージョンです。実際のデフォルト値には、追加のテキストプロパティ指定も含まれます。

("-"
 mode-line-mule-info
 mode-line-modified
 mode-line-frame-identification
 mode-line-buffer-identification

 "   "
 mode-line-position
 (vc-mode vc-mode)
 "   "

 mode-line-modes
 (which-func-mode ("" which-func-format "--"))
 (global-mode-string ("--" global-mode-string))
 "-%-")

23.4.5 モードラインでの`%`構造

モードライン構成として使用される文字列は、さまざまな種類のデータを置き換えるために、%構成を使用できます。以下は、定義済みの%構成と意味のリストです。

‘%%’以外の構成では、フィールドの最小幅を指定するために、‘%’の後に10進整数を追加できます。幅がそれより小さい場合、そのフィールドは最小幅にパディングされます。純粋に数値的な構成(‘c’、‘i’、‘I’、‘l’)は左側、それ以外は右側にスペースを追加してパディングされます。

%b: buffer-name関数により取得されるカレントバッファー名。バッファーの名前を参照のこと。
%c: The current column number of point, counting from zero starting at the left margin of the window.
%C: The current column number of point, counting from one starting at the left margin of the window.
%e: EmacsがLispオブジェクトにたいしてメモリー不足になりそうなときは、それを伝える簡略なメッセージを示す。それ以外の場合は空である。
%f: buffer-file-name関数により取得される、visitしているファイル名。バッファーのファイル名を参照のこと。
%F: 選択されたフレームのタイトル(ウィンドウシステム上のみ)、または名前。基本パラメーターを参照のこと。
%i: カレントバッファーのアクセス可能な範囲のサイズ。基本的には(- (point-max) (point-min))。
%I: ‘%i’と同様だが、10^3は‘k’、10^6は‘M’、10^9は‘G’を使用して省略することにより、より読みやすい方法でサイズをプリントする。
%l: ポイント位置のカレント行番号。そのバッファーのアクセス可能な範囲内でカウントされる。
%n: ナローイングが有効なときは‘Narrow’、それ以外は何も表示しない(ナローイングのnarrow-to-regionを参照されたい)。
%o: The degree of travel of the window through (the visible portion of) the buffer, i.e. the size of the text above the top of the window expressed as a percentage of all the text outside the window, or ‘Top’, ‘Bottom’ or ‘All’.
%p: ウィンドウの最上部より上にあるバッファーテキストのパーセント表示、または‘Top’、‘Bottom’、‘All’のいずれか。デフォルトのモードライン構成は、これを3文字に切り詰めることに注意されたい。
%P: ウィンドウの最下部より上にあるバッファーテキスト(ウィンドウ内の可視なテキストと、最上部の上にあるテキスト)のパーセント表示、およびバッファーの最上部がスクリーン上で可視な場合は、それに加えて‘Top’。または‘Bottom’か‘All’。
%q: The percentages of text above both the top and the bottom of the window, separated by ‘-’, or ‘All’.
%s: process-statusにより取得される、カレントバッファーに属するサブプロセスの状態。プロセスの情報を参照のこと。
%z: キーボード、端末、およびバッファーコーディングシステムのニーモニック。
%Z: ‘%z’と同様だが、EOL形式(end-of-line format: 改行形式)を含む。
%*: バッファーが読み取り専用(buffer-read-onlyを参照)の場合は‘%’、
変更されている場合(buffer-modified-pを参照)は‘*’、
それ以外は‘-’。バッファーの変更を参照のこと。
%+: バッファーが変更されている場合(buffer-modified-pを参照)は‘*’
バッファーが読み取り専用(buffer-read-onlyを参照)の場合は‘%’、
それ以外は‘-’。これは、読み取り専用バッファーの変更にたいしてのみ‘%*’と異なる。バッファーの変更を参照のこと。
%&: バッファーが変更されている場合は‘*’、それ以外は‘-’。
%[: 再帰編集レベルの深さを標示する(ミニバッファーレベルは勘定しない)。1つの編集レベルが‘[’。再帰編集を参照のこと。
%]: 1つの編集レベルが‘]’(ミニバッファーレベルは勘定しない)。
%-: モードラインの残りを充填するのに十分なダッシュ。
%%: 文字‘%’。%構成が許される文字列内に、リテラル‘%’を含めるには、この方法を使用する。

以下の2つの%構成はまだサポートされていますが、同じ結果を変数mode-nameとglobal-mode-stringで取得できるので、これらは時代遅れです。

%m: mode-nameの値。
%M: global-mode-stringの値。

23.4.6 モードラインでのプロパティ

モードライン内では、特定のテキストプロパティが意味をもちます。faceプロパティは、テキストの外見に影響します。help-echoプロパティはそのテキストのヘルプ文字列に関連し、keymapによりテキストをマウスに感応させることができます。

モードライン内のテキストにたいしてテキストプロパティを指定するには、4つの方法があります:

モードラインデータ構造内に、テキストプロパティをもつ文字列を直接配する。
‘%12b’のような、モードライン%構成に、テキストプロパティを配する。その場合、%構成を展開すると、同じテキストプロパティをもつことになる。
propsで指定されるテキストプロパティをeltに与えるために、(:propertize elt props…)構成を使用する。
formがテキストプロパティをもつ文字列に評価されるように、モードラインデータ構造内に:eval formを含むリストを使用する。

キーマップを指定するために、keymapプロパティを使用できます。このキーマップは、マウスクリックにたいしてのみ、実際の効果をもちます。モードライン内にポイントを移動させるのは不可能なので、文字キーやファンクションキーをこれにバインドしても、効果はありません。

モードラインが、risky-local-variableが非nilであるようなプロパティをもつ変数を参照する場合、その変数の値により与える、または指定されるテキストプロパティは、すべて無視されます。これは、そのようなプロパティは呼び出される関数を指定するかもしれず、その関数はファイルローカル変数が由来かもしれないからです。

23.4.7 ウィンドウのヘッダーライン

ウィンドウは、最下部にモードラインをもつことができるのと同じように、最上部にヘッダーライン(header line)をもつことができます。ヘッダーライン機能は、それがheader-line-formatにより制御されることを除けば、モードラインと同じように機能します。

Variable: header-line-format: すべてのバッファーにたいしてローカルなこの変数は、そのバッファーを表示するバッファーにたいして、ヘッダーラインを表示する方法を指定する。この変数の値のフォーマットは、mode-line-formatにたいするフォーマットと同じである(モードラインのデータ構造を参照)。通常、この変数はnilなので、通常のバッファーはヘッダーラインをもたない。

Function: window-header-line-height &optional window: この関数は、windowのヘッダーラインの高さを、ピクセルでリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。

高さが1行しかないウィンドウは、決してヘッダーラインを表示しません。また、高さが2行しかないウィンドウは、一度にモードラインとヘッダーラインを表示できません。そのようなウィンドウがモードラインをもつ場合、ヘッダーラインは表示されません。

23.4.8 モードラインのフォーマットのエミュレート

関数format-mode-lineを使用して、特定のモードライン構成にもとづきモードライン、またはヘッダーラインに表示されるテキストを計算できます。

Function: format-mode-line format &optional face window buffer

この関数は、あたかもwindowにたいしてモードラインを生成するかのように、formatに応じてテキスト行をフォーマットするが、さらにそのテキストを文字列としてリターンする。引数windowのデフォルトは、選択されたウィンドウである。bufferが非nilの場合、使用されるすべての情報はbufferから取得される。デフォルトでは、windowのバッファーから取得される。

文字列の値は通常、モードラインがもつであろうフェイス、キーマップ等に対応するテキストプロパティをもつ。formatにより指定されたfaceプロパティのないすべての文字は、faceにより決定されるデフォルト値を取得する。faceがtの場合は、windowが選択されていればmode-line、それ以外はmode-line-inactiveであることを意味する。faceがnil、または省略された場合は、デフォルトのフェイスを意味する。faceが整数の場合、この関数はテキストプロパティをもたない値をリターンするだろう。

faceの値として、他の有効なフェイスを指定することもできる。指定された場合、それはformatでフェイスを指定されていない文字のfaceプロパティのフェイスを提供する。

faceとしてmode-line、mode-line-inactive、header-lineを使用することにより、フォーマットされた文字列のリターンに加えて、対応するフェイスのカレント定義を使用して、実際にモードラインやヘッダーラインが再描画されるだろうということに注意されたい(他のフェイスでは、再描画は行われない)。

たとえば、(format-mode-line header-line-format)は選択されたウィンドウに表示されるテキスト(ヘッダーラインがない場合は"")をリターンするだろう。(format-mode-line header-line-format 'header-line)は、各文字がヘッダーライン内でもつであろうフェイスをもつ、同じテキストをリターンし、加えてヘッダーラインの再描画も行う。

23.5 Imenu

Imenuとは、バッファー内の定義やセクションをすべてリストするメニューをユーザー選択することにより、バッファー内の該当箇所に直接移動する機能です。Imenuは、定義(またはバッファーのその他の名前つき範囲)の名前とその定義のバッファー内での位置をリストする、バッファーインデックスを構築して、ユーザーがそれを選択すればポイントをおこに移動できるようにして機能します。メジャーモードは、imenu-add-to-menubarを使用して、メニューバーアイテムを追加することができます。

Command: imenu-add-to-menubar name: この関数は、nameという名前のImenuを実行するためのローカルメニューバーを定義する。

Imenuを使用ためのユーザーレベルコマンドは、Emacsマニュアル内で説明されています(Imenu in the Emacs Manualを参照)。このセクションでは、特定のメジャーモードにたいして、定義や名前つき範囲を見つける、Imenuメソッドのカスタマイズ方法を説明します。

変数imenu-generic-expressionをセットするのが通常の、そしてもっともシンプルな方法です:

Variable: imenu-generic-expression

この変数が非nilの場合、それはImenuにたいして定義を探すための正規表現を指定するリストである。シンプルなimenu-generic-expressionの要素は、以下のようになる:

(menu-title regexp index)

ここで、menu-titleが非nilの場合、それはこの要素にたいするマッチが、バッファーインデックスのサブメニューとなることを告げる。menu-title自体は、そのサブメニューにたいして名前を指定する。menu-titleがnil,の場合は、この要素にたいするマッチは、直接トップレベルのバッファーインデックスとなる。

このリストの2つ目の要素regexpは、正規表現である(正規表現を参照)。これは、バッファー内でこれにマッチするものは定義、あるいはバッファーインデックス内に記載すべき何かであると判断される。3つ目の要素indexは、0以上の整数の場合は、regexp内の部分式(subexpression)が定義名にマッチすることを示します。

以下のような要素もある:

(menu-title regexp index function arguments…)

この要素にたいする各マッチはインデックスアイテムを作成し、ユーザーによりそのインデックスアイテムが選択されたとき、アイテム名、バッファー位置、およびargumentsから構成される引数で、functionを呼び出す。

Emacs Lispモードにたいしては、imenu-generic-expressionは以下のようになるだろう:

((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)

 ("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)

 ("*Types*"
  "^\\s-*\
(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

Variable: imenu-case-fold-search

この変数は、imenu-generic-expressionの値中の正規表現マッチが、大文字小文字を区別するかどうかを制御する。t,(デフォルト)の場合は、大文字小文字の違いを無視することを意味する。

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

Variable: imenu-syntax-alist

この変数は、imenu-generic-expression処理中に、カレントバッファーの構文テーブルをオーバーライドして使用する、構文テーブル変更用のalistである。このalistの各要素は、以下の形式をもつべきである:

(characters . syntax-description)

CARのcharactersには、文字または文字列を指定できる。この要素は、その文字、または文字列がsyntax-descriptionにより指定される構文でありことを示し、modify-syntax-entryに渡される(構文テーブルの関数を参照)。

典型的には、この機能は通常はシンボル構文(symbol syntax)をもつ文字にたいして単語構文(word syntax)を与えるために使用され、それによりimenu-generic-expressionが単純になり、マッチングのスピードも向上する。たとえば、Fortranモードは以下のようにこれを使用する:

(setq imenu-syntax-alist '(("_$" . "w")))

imenu-generic-expressionの正規表現は、‘\$\\sw\\|\\s_\$+’のかわりに、‘\\sw+’を使用できる。このテクニックは、モードの名前として許されるより短い、頭文字に名前を制限する必要があるときは、不便かもしれないことに注意されたい。

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

あるメジャーモードにたいしてImenuをカスタマイズする別の方法には、imenu-prev-index-position-functionとimenu-extract-index-name-functionがあります:

Variable: imenu-prev-index-position-function

If this variable is non-nil, its value should be a function that finds the next definition to put in the buffer index, scanning backward in the buffer from point. It should return nil if it doesn’t find another definition before point. Otherwise it should leave point at the place it finds a definition and return any non-nil value.

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

Variable: imenu-extract-index-name-function

この変数が非nilの場合、その値はポイントが定義中にある(imenu-prev-index-position-function関数がポイントを残す場所)という想定の元、その定義の名前をリターンする関数であること。

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

メジャーモードにたいしてImenuをカスタマイズするための最後の方法は、変数imenu-create-index-functionのセットです:

Variable: imenu-create-index-function

この変数は、バッファーインデックスを作成するために使用する関数を指定する。この関数は、引数がをとらず、カレントバッファーにたいするインデックスalist(index alist)をリターンすべきである。この関数はsave-excursion内で呼び出されるので、どこにポイントを残しても違いはない。

このインデックスalistは、3つのタイプの要素をもつことができる。以下は、シンプル要素(simple element)の例である:

(index-name . index-position)

シンプル要素の選択は、そのバッファー内の位置index-positionに移動する効果をもつ。スペシャル要素(special element)は、以下のようなものである:

(index-name index-position function arguments…)

スペシャル要素の選択により、以下が処理される:

(funcall function
         index-name index-position arguments…)

ネストされたサブalist要素(nested sub-alist element)は、以下のようなものである:

(menu-title . sub-alist)

これは、sub-alistにより指定される、サブメニューmenu-titleを作成する。

imenu-create-index-functionのデフォルト値は、imenu-default-create-index-functionである。この関数は、インデックスalistを生成するために、imenu-prev-index-position-functionの値と、imenu-extract-index-name-functionの値を呼び出す。しかし、これら2つ変数のいずれかがnilの場合、デフォルト関数はかわりにimenu-generic-expressionを使用する。

この変数をセットすることにより、カレントバッファーにたいしてバッファーローカルになる。

23.6 Font Lockモード

Font Lockモードとは、バッファーの特定の部分にたいして、それらの構文的役割(syntactic role)にもとづき、自動的にfaceプロパティをアタッチする、バッファーローカルなマイナーモードです。このモードがバッファーをパースする方法は、そのメジャーモードに依存します。ほとんどのメジャーモードは、どのコンテキストでどのフェイスを使用するかにたいして、構文的条件(syntactic criteria)を定義します。このセクションでは、特定のメジャーモードにたいして、Font Lockをカスタマイズする方法を説明します。

Font Lockモードは、2つの方法によりハイライトするテキストを探します。それは構文テーブル(syntax table)にもとづく構文解析と、(通常は正規表現にたいする)検索です。最初に構文的フォント表示(syntactic fontification)が発生します。これはコメントと文字列定数を見つけて、それらをハイライトします。検索ベースのフォント表示が発生するのは、2番目です。

23.6.1 Font Lockの基礎		Font Lockカスタマイズの概要。
23.6.2 検索ベースのフォント化		正規表現にもとづくフォント表示。
23.6.3 検索ベースのフォント化のカスタマイズ		検索ベースフォント表示のカスタマイズ。
23.6.4 Font Lockのその他の変数		追加のカスタマイズ機能。
23.6.5 Font Lockのレベル		多なりとも少ユーザーが選択できるように、それぞれのモードは代替レベルを定義できる。
23.6.6 事前計算されたフォント化		バッファーコンテンツを生成するLispプログラムが、どのようにしてそれをフォント表示する方法も指定できるか。
23.6.7 Font Lockのためのフェイス		Font Lockにたいする具体的な特殊フェイス。
23.6.8 構文的なFont Lock		構文テーブルにもとづくフォント表示。
23.6.9 複数行のFont Lock構造		Font Lockに複数行構成の正しいハイライトを強制する方法。

23.6.1 Font Lockの基礎

The Font Lock functionality is based on several basic functions. Each of these calls the function specified by the corresponding variable. This indirection allows major and minor modes to modify the way fontification works in the buffers of that mode, and even use the Font Lock mechanisms for features that have nothing to do with fontification. (This is why the description below says “should” when it describes what the functions do: the mode can customize the values of the corresponding variables to do something entirely different.) The variables mentioned below are described in Font Lockのその他の変数.

font-lock-fontify-buffer: This function should fontify the current buffer’s accessible portion, by calling the function specified by font-lock-fontify-buffer-function.
font-lock-unfontify-buffer: Used when turning Font Lock off to remove the fontification. Calls the function specified by font-lock-unfontify-buffer-function.
font-lock-fontify-region beg end &optional loudly: Should fontify the region between beg and end. If loudly is non-nil, should display status messages while fontifying. Calls the function specified by font-lock-fontify-region-function.
font-lock-unfontify-region beg end: Should remove fontification from the region between beg and end. Calls the function specified by font-lock-unfontify-region-function.
font-lock-flush &optional beg end: This function should mark the fontification of the region between beg and end as outdated. If not specified or nil, beg and end default to the beginning and end of the buffer’s accessible portion. Calls the function specified by font-lock-flush-function.
font-lock-ensure &optional beg end: This function should make sure the region between beg and end has been fontified. The optional arguments beg and end default to the beginning and the end of the buffer’s accessible portion. Calls the function specified by font-lock-ensure-function.

Font Lockモードがテキストをハイライトする方法を制御する変数が、いくつかあります。しかし、メジャーモードは、これらの変数を直接セットするべきではありません。かわりに、メジャーモードはバッファーローカル変数として、font-lock-defaultsをセットするべきです。Font Lockモードが有効なときは、他のすべての変数をセットするために、この変数に割り当てられた値が使用されます。

Variable: font-lock-defaults

This variable is set by modes to specify how to fontify text in that mode. It automatically becomes buffer-local when set. If its value is nil, Font Lock mode does no highlighting, and you can use the ‘Faces’ menu (under ‘Edit’ and then ‘Text Properties’ in the menu bar) to assign faces explicitly to text in the buffer.

非nilの場合、値は以下のようであること:

(keywords [keywords-only [case-fold
 [syntax-alist other-vars…]]])

1つ目の要素keywordsは、検索ベースのフォント表示を制御するfont-lock-keywordsの値を、間接的に指定する。値にはシンボル、変数、またはfont-lock-keywordsにたいして使用するリストが値であるような関数を指定できる。また、それぞれのシンボルがフォント表示の可能なレベルであるような、いくつかのシンボルからなるリストも指定できる。この場合、1つ目のシンボルはフォント表示の‘モードデフォルト(mode default)’レベル、次のシンボルはフォント表示のレベル1、その次はレベル2、のようになる。通常、‘モードデフォルト’レベルはレベル1と等しい。これは、font-lock-maximum-decorationがnil値をもつとき使用される。Font Lockのレベルを参照のこと。

2つ目の要素keywords-onlyは、変数font-lock-keywords-onlyの値を指定する。これが省略、またはnilの場合は、(文字列とコメントの)構文的フォント表示も行われる。非nilの場合は、構文的フォント表示は行われない。構文的なFont Lockを参照のこと。

3つ目の要素case-foldは、font-lock-keywords-case-fold-searchの値を指定する。非nilの場合、検索ベースフォント表示の間、Font Lockモードは大文字小文字の違いを無視する。

4つ目の要素syntax-alistが非nilの場合、それは(char-or-string . string)という形式のコンスセルのリストであること。これらは、構文的フォント表示にたいする構文テーブルのセットアップに使用される。結果となる構文テーブルは、font-lock-syntax-tableに格納される。syntax-alistが省略、またはnilの場合、構文的フォント表示はsyntax-table関数によりリターンされる構文テーブルを使用する。構文テーブルの関数を参照のこと。

(もしあれば)残りすべての要素は、まとめてother-varsと呼ばれる。これらの要素はすべて、(variable . value)という形式をもつべきである。これは、variableをバッファーローカルにしてから、それにvalueをセットすることを意味する。これらother-varsを使用して、最初の5つの要素による制御とは別に、フォント表示に影響する他の変数をセットできる。Font Lockのその他の変数を参照のこと。

モードがfont-lock-faceプロパティ追加により明示的にテキストをフォント表示する場合は、自動的なフォント表示すべてをオフにするために、font-lock-defaultsに(nil t)を指定できます。しかし、これは必須ではありません。font-lock-faceを使用して何かをフォント表示して、それ以外の部分のテキストを自動的にフォント表示するようにセットアップするのは可能です。

23.6.2 検索ベースのフォント化

検索ベースフォント表示を直接制御する変数は、font-lock-keywordsです。この変数は通常、font-lock-defaults内の要素keywordsを通じて指定されます。

Variable: font-lock-keywords: この変数の値は、ハイライトするキーワードのリストである。Lispプログラムは、この変数を直接セッすべきでない。通常は、font-lock-defaults内の要素keywordsを使用して、Font Lockモードが自動的に値をセットする。この値は、関数font-lock-add-keywordsおよびfont-lock-remove-keywordsを使用して、変更されることもあり得る(検索ベースのフォント化のカスタマイズを参照)。

font-lock-keywordsの各要素は、特定のケースに該当するテキストを見つける方法、およびそれらをハイライトする方法を指定します。Font Lockモードは、font-lock-keywordsの要素をちくじ処理してマッチを探して、すべてのマッチを処理します。通常は、テキストの一部はすでに一度はフォント表示されており、同じテキスト内で連続するマッチによるこれをオーバーライドはできません。しかし、subexp-highlighterの要素overrideを使用して、異なる挙動を指定できます。

font-lock-keywordsの各要素は、以下の形式のいずれかをもつべきです:

regexp

font-lock-keyword-faceを使用して、regexpにたいするすべてのマッチをハイライトする。たとえば、

;; font-lock-keyword-faceを使用して
;; 単語‘foo’をハイライトする
"\\<foo\\>"

これらの正規表現を作成するときは、慎重に行うこと。下手に記述されたパターンにより、スピードが劇的に低下し得る! 関数regexp-opt(正規表現の関数を参照)は、いくつかのキーワードとマッチするために最適な正規表現の計算に有用である。

function

functionを呼び出すことによりテキストを探し、font-lock-keyword-faceを使用して見つかったマッチをハイライトする。

functionは、呼び出される際に1つの引数(検索のリミット)を受け取る。検索はポイント位置から開始し、そのリミットを超えた検索は行うべきではない。これは、検索が成功した場合は非nilをリターンして、見つかったマッチを表すマッチデータをセットすべきである。nilのリターンは、検索の失敗を示す。

フォント表示は、前の呼び出しでポイントが残された位置から、同じリミットを用いてfunctionを呼び出し、functionが失敗するまでfunctionを繰り返し呼び出すだろう。検索が失敗しても、何らかの特別な方法により、functionがポイントをリセットする必要はない。

(matcher . subexp)

この種の要素では、matcherは上述のregexpかfunctionのいずれかである。CDRのsubexpは、(matcherがマッチするテキスト全体のかわりに)matcherのどの部分式(subexpression)がハイライトされるべきかを指定する。

;; font-lock-keyword-faceHを使用して
;; ‘bar’が‘fubar’の一部のときに
;; ハイライトする
("fu\\(bar\\)" . 1)

正規表現matcherの生成にregexp-optを使用する場合は、subexpにたいする値の計算にregexp-opt-depth(正規表現の関数を参照)を使用できる。

(matcher . facespec)

この種の要素では、facespecの値がハイライトに使用するフェイスを指定する。もっともシンプルな例では、facespecは値がフェイス名であるようなはLisp変数(シンボル)である。

;; fubar-faceの値のフェイスを使用して
;; ‘fubar’をハイライトする
("fubar" . fubar-face)

しかし、facespecは以下のような形式のリストに評価されてもよい:

(face face prop1 val1 prop2 val2…)

これは、マッチしたテキストにフェイスfaceを指定し、さまざまなテキストプロパティをputする。これを行う場合は、この方法によりfont-lock-extra-managed-propsに値をセットする、他のテキストプロパティ名を確実に追加すること。そうすれば、それらのプロパティが妥当性を失ったとき、それらのプロパティもクリアーされるだろう。これらのプロパティをクリアーする関数を、変数font-lock-unfontify-region-functionにセットすることもできる。Font Lockのその他の変数を参照のこと。

(matcher . subexp-highlighter)

この種の要素では、subexp-highlighterはmatcherにより見つかったマッチをハイライトする方法を指定するリストである。これは、以下の形式をもつ。

(subexp facespec [override [laxmatch]])

CARのsubexpは、マッチのどの部分式をフォント表示するかを指定する整数である(0はマッチしたテキスト全体を意味する)。これの2つ目の要素facespecは、上述したような値がフェイスを指定するような式である。

subexp-highlighter内の残りの値overrideとlaxmatchは、オプションのフラグである。overrideがtの場合、この要素は前のfont-lock-keywordsの要素により作成された既存のフォント表示をオーバーライドできる。値がkeepの場合は、すでに他の要素によりフォント表示されていない文字がフォント表示される。値がprependの場合は、facespecにより指定されたフェイスが、font-lock-faceプロパティの先頭に追加される。値がappendの場合は、そのフェイスがfont-lock-faceプロパティの最後に追加される。

laxmatchが非nilの場合、それはmatcher内で番号付けされた部分式subexpが存在しなくても、エラーにならないことを意味する。当然、番号付けされた部分式subexpのフォント表示は発生しない。しかし、他の部分式(と他のregexp)のフォント表示は継続されるだろう。laxmatchがnilで、指定された部分式が存在しない場合は、エラーがシグナルされて検索ベースのフォント表示は終了する。

以下はこのタイプの要素と、それが何を行うかの例である:

;; foo-bar-faceを使用して、たとえハイライト済みでも
;; ‘foo’と‘bar’をハイライトする
;; foo-bar-faceは値がフェイスであるような変数であること
("foo\\|bar" 0 foo-bar-face t)

;; fubar-faceの値のフェイスを使用して
;; 関数fubar-matchが見つけた各マッチの
;; 最初の部分式をハイライトする
(fubar-match 1 fubar-face)

(matcher . anchored-highlighter)

この種の要素では、anchored-highlighterはmatcherが見つけたマッチに後続するテキストをハイライトする方法を指定する。つまり、matcherが見つけたマッチは、anchored-highlighterにより指定されるその先の検索にたいする、アンカー(anchor)として機能する。anchored-highlighterは、以下の形式のリストである:

(anchored-matcher pre-form post-form
                        subexp-highlighters…)

ここで、anchored-matcherはmatcherと同様、正規表現か関数である。matcherにたいするマッチを見つけた後に、ポイントはそのマッチの終端に移動する。そこで、Font Lockはフォームpre-formを評価する。それからanchored-matcherにたいするマッチを検索し、subexp-highlightersを使用して、それらのマッチをハイライトする。subexp-highlighterについては上記を参照のこと。最後にFont Lockはpost-formを評価する。

フォームpre-formおよびpost-formは、anchored-matcher使用時の事前の初期化、事後のクリーンアップに使用され得る。通常、pre-formはanchored-matcherを開始する前に、matcherのマッチに関連する何らかの位置にポイントを移動するために使用される。post-formは、matcherを再開する前に、ポイントを戻すために使用されるかもしれない。

pre-formを評価した後、Font Lockはその行の終端の先にたいして、anchored-matcherの検索を行わない。しかし、pre-formがpre-form評価後のポイント位置より大きいバッファー位置をリターンした場合には、かわりにpre-formによりリターンされた位置が検索リミットとして使用される。一般的に、その行の終端より大きい位置をリターンするのは、よいアイデアではない。言い換えると、anchored-matcher検索は複数行にわたる(span lines)べきではないと言えよう。

たとえば、

;; item-faceの値を使用して
;; 単語‘anchor’に(同一行内で)
;; 後続する単語‘item’をハイライトする
("\\<anchor\\>" "\\<item\\>" nil nil (0 item-face))

ここで、pre-formとpost-formはnilである。したがって、‘item’にたいする検索は‘anchor’にたいするマッチの終端から開始され、後続する‘anchor’インスタンスにたいする検索は、‘item’にたいする検索が終了した位置から再開される。

(matcher highlighters…)

この種の要素は、単一のmatcherにたいして、複数のhighlighterリストを指定する。highlighterリストには、上述したsubexp-highlighter、またはanchored-highlighterのいずれかを指定できる。

たとえば、

;; anchor-faceの値内に現れる単語‘anchor’、
;; および、(同じ行の)後続のitem-faceの
;;  値内に現れる単語‘item’をハイライトする
("\\<anchor\\>" (0 anchor-face)
                ("\\<item\\>" nil nil (0 item-face)))

(eval . form)

ここでformは、バッファー内でこのfont-lock-keywordsの値が最初に使用されるときに評価される式である。この値は、上述のこのテーブルで説明した、いずれかの形式をもつべきである。

警告: 複数行にわたるテキストにたいするマッチさせるために、font-lock-keywordsの要素をデザインしてはならない。これは確実に機能するとは言えない。詳細は、複数行のFont Lock構造を参照のこと。

検索ベースのフォント表示が大文字小文字を区別すべきかどうかを告げるfont-lock-keywords-case-fold-searchの値を指定するために、font-lock-defaults内でcase-foldを使用できる。

Variable: font-lock-keywords-case-fold-search: 非nilは、font-lock-keywordsのための正規表現マッチングが、大文字小文字を区別すべきではないことを意味する。

23.6.3 検索ベースのフォント化のカスタマイズ

メジャーモードにたいして検索ベースフォント表示ルールを追加するためにfont-lock-add-keywords、削除にはfont-lock-remove-keywordsを使用することができます。

Function: font-lock-add-keywords mode keywords &optional how

この関数は、カレントバッファー、またはメジャーモードmodeにたいして、ハイライトするkeywordsを追加する。引数keywordsは、変数font-lock-keywordsと同じ形式のリストであること。

modeが、c-modeのような、あるメジャーモードのコマンド名であるようなシンボルの場合には、そのmode内でFont Lockモードを有効にすることにより、keywordsがfont-lock-keywordsに追加される効果がある。非nil値のmodeによる呼び出しは、~/.emacsファイル内でのみ正しい。

modeがnilの場合、この関数はカレントバッファーのfont-lock-keywordsにkeywordsを追加する。この方法でのfont-lock-add-keywords呼び出しは、通常はモードフック関数内で使用される。

デフォルトでは、keywordsはfont-lock-keywordsの先頭に追加される。オプション引数howがsetの場合、それらはfont-lock-keywordsの値の置換に使用される。howがそれ以外の非nil値の場合、これらはfont-lock-keywordsの最後に追加される。

追加のハイライトパターンの使用を可能にする、特別なサポートを提供するモードがいくつかある。それらの例については、変数c-font-lock-extra-types、c++-font-lock-extra-types、java-font-lock-extra-typesを参照のこと。

警告: メジャーモードコマンドは、モードフックを除き、いかなる状況においても、直接間接を問わずfont-lock-add-keywordsを呼び出してはならない(これを行うと、いくつかのマイナーモードは不正な振る舞いを起こしかねない)。メジャーモードコマンドは、font-lock-keywordsをセットすることにより、検索ベースフォント表示のルールをセットアップすべきである。

Function: font-lock-remove-keywords mode keywords: This function removes keywords from font-lock-keywords for the current buffer or for major mode mode. As in font-lock-add-keywords, mode should be a major mode command name or nil. All the caveats and requirements for font-lock-add-keywords apply here too. The argument keywords must exactly match the one used by the corresponding font-lock-add-keywords.

たとえば、以下はCモードに2つのフォント表示パターンを追加するコードの例である。フォント表示の1つは、たとえコメント内であろうとも単語‘FIXME’をフォント表示し、もう1つは‘and’、‘or’、‘not’をキーワードとしてフォント表示する。

(font-lock-add-keywords 'c-mode
 '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
   ("\\<\\(and\\|or\\|not\\)\\>" . font-lock-keyword-face)))

この例は、正にCモードだけに効果がある。Cモード、およびその派生モードにたいして同じパターンを追加するには、かわりに以下を行う:

(add-hook 'c-mode-hook
 (lambda ()
  (font-lock-add-keywords nil
   '(("\\<\\(FIXME\\):" 1 font-lock-warning-face prepend)
     ("\\<\\(and\\|or\\|not\\)\\>" .
      font-lock-keyword-face)))))

23.6.4 Font Lockのその他の変数

このセクションでは、font-lock-defaults内のother-varsを用いて、メジャーモードがセットできる追加の変数について説明します(Font Lockの基礎を参照)。

Variable: font-lock-mark-block-function

この変数が非nilの場合、それはコマンドM-o M-o(font-lock-fontify-block)で再フォント表示するテキスト範囲を選択するために、引数なしで呼び出される関数であること。

この関数は、結果を報告するために、選択されたテキスト範囲にリージョンを配すべきである。正しい結果を与えるのに十分、かつ再フォント表示が低速にならない程度のテキスト範囲を選択するのがよい。プログラミングのモードにたいしてはmark-defun、テキストを扱うモードにたいしてはmark-paragraphが典型的な値である。

Variable: font-lock-extra-managed-props: この変数は、(font-lock-face以外の)Font Lockにより管理される追加プロパティを指定する。これらの追加プロパティは、通常はfont-lock-faceプロパティだけを管理する、font-lock-default-unfontify-regionにより使用される。他のプロパティも同様にFont Lockに管理させたい場合は、このリストに追加するのと同じように、font-lock-keywords内のfacespec内でもこれらを指定しなければならない。検索ベースのフォント化を参照のこと。

Variable: font-lock-fontify-buffer-function: そのバッファーをフォント表示するために使用する関数。デフォルト値はfont-lock-default-fontify-buffer。

Variable: font-lock-unfontify-buffer-function: そのバッファーを非フォント表示するために使用する関数。デフォルト値はfont-lock-default-unfontify-buffer。

Variable: font-lock-fontify-region-function: リージョンをフォント表示するための関数。この関数は、リージョンの開始と終了の2つを引数にとり、オプションで3つ目の引数verboseをとるべきである。verboseが非nilの場合、その関数はステータスメッセージをプリントすべきである。デフォルト値はfont-lock-default-fontify-region。

Variable: font-lock-unfontify-region-function: リージョンを非フォント表示するための関数。この関数は、リージョンの開始と終了の2つを引数にとるべきである。デフォルト値はfont-lock-default-unfontify-region。

Variable: font-lock-flush-function: Function to use for declaring that a region’s fontification is out of date. It takes two arguments, the beginning and end of the region. The default value of this variable is font-lock-after-change-function.

Variable: font-lock-ensure-function: Function to use for making sure a region of the current buffer has been fontified. It is called with two arguments, the beginning and end of the region. The default value of this variable is a function that calls font-lock-default-fontify-buffer if the buffer is not fontified; the effect is to make sure the entire accessible portion of the buffer is fontified.

Function: jit-lock-register function &optional contextual

この関数は、カレントバッファーの一部をフォント表示/非表示する必要がある任意のタイミングで、Font LockモードがLisp関数functionを実行することを宣言する。これは、デフォルトのフォント表示関数が呼び出される前に、フォント表示/非表示するリージョンを指定する2つの引数startとendでfunctionを呼び出す。

オプション引数contextualが非nilの場合は、行が更新されたときに限らず、そのバッファーの構文的に関連する部分を常にフォント表示するよう、Font Lockモードに強制する。この引数は、通常は省略できる。

Function: jit-lock-unregister function: 以前にjit-lock-registerを使用して、フォント表示関数としてfunctionを登録した場合は、その関数を未登録にする。

23.6.5 Font Lockのレベル

フォント表示にたいして3つの異なるレベルを提供するモードが、いくつかあります。font-lock-defaults内のkeywordsにたいしてシンボルのリストを使用することにより、複数のレベルを定義できます。このリストのシンボルはそれぞれ、フォント表示の1レベルを指定します。これらのレベルの選択は、通常はfont-lock-maximum-decorationをセットすることにより、ユーザーの責任で行われます(Font Lock in the GNU Emacs Manualを参照)。選択されたレベルのシンボルの値は、font-lock-keywordsの初期化に使用されます。

フォント表示レベルの定義方法に関する慣習を以下に挙げます:

レベル1: 関数宣言、(includeやimportのような)ファイルディレクティブ、文字列、コメントをハイライトする。これは、もっとも重要かつトップレベルのコンポーネントだけをフォント表示すれば高速になるという発想である。
レベル2: レベル1に加えて、すべての言語のキーワード(キーワードと同様に作用する型名を含む)、および名前付き定数値をハイライトする。これは、(構文的、または意味的な)すべてのキーワードは適切にフォント表示されるべきという発想である。
レベル3: レベル2に加えて、関数内で定義されるシンボル、変数宣言、およびすべてのビルトイン関数名にたいして、それがどこに出現しようとハイライトする。

23.6.6 事前計算されたフォント化

list-buffersやoccurのようないくつかのメジャーモードは、バッファーのテキストをプログラム的に構築します。これらにたいしてFont Lockモードをサポートするには、そのバッファーにテキストを挿入するタイミングで、テキストのフェイスを指定するのが、もっとも簡単な方法です。

これは、スペシャルテキストプロパティfont-lock-face(特殊な意味をもつプロパティを参照)により、テキスト内にフェイスを指定することにより行われます。Font Lockモードが有効になったとき、このプロパティはfaceと同じように、表示を制御します。Font Lockモードが無効になると、font-lock-faceは表示に効果をもちません。

モードが、通常のFont Lockメカニズムとともに、あるテキストにたいしてfont-lock-faceを使用しても問題はありません。しかし、そのモードが通常のFont Lockメカニズムを使用しない場合は、変数font-lock-faceをセットするべきではありません。

23.6.7 Font Lockのためのフェイス

Font Lockモードは、ハイライトに任意のフェイスを使用できますが、Emacsは、特にFontLockがテキストのハイライトに使用するいくつかのフェイスを定義しています。これらのFont Lockフェイス(Font Lock faces)を、以下にリストします。これらのフェイスは、FontLockモードの外部における構文的なハイライトでメジャーモードが使用することもできます(メジャーモードの慣習を参照)。

以下の各シンボルは、フェイス名であり、かつデフォルト値がシンボル自身であるような変数でもあります。つまり、font-lock-comment-faceのデフォルト値はfont-lock-comment-faceです。

The faces are listed with descriptions of their typical usage, and in order of greater to lesser prominence. If a mode’s syntactic categories do not fit well with the usage descriptions, the faces can be assigned using the ordering as a guide.

font-lock-warning-face: Emacs Lispの‘;;;###autoload’、Cの‘#error’のような、特有な構文、またはその他のテキスト意味を大きく変更する構文にたいして使用される。
font-lock-function-name-face: 定義、または宣言される関数の名前にたいして使用される。
font-lock-variable-name-face: 定義、または宣言される変数の名前にたいして使用される。
font-lock-keyword-face: Cの‘for’や‘if’のように、特別な構文的意味をもつキーワードにたいして使用される。
font-lock-comment-face: コメントにたいして使用される。
font-lock-comment-delimiter-face: Cの‘/*’と‘*/’のような、コメント区切りにたいして使用される。ほとんどの端末では、このフェイスはfont-lock-comment-faceを継承する。
font-lock-type-face: ユーザー定義データ型にたいして使用される。
font-lock-constant-face: Cの‘NULL’のような、定数の名前にたいして使用される。
font-lock-builtin-face: ビルトイン関数の名前にたいして使用される。
font-lock-preprocessor-face: プロセッサーコマンドにたいして使用される。デフォルトでは、font-lock-builtin-faceを継承する。
font-lock-string-face: 文字列定数にたいして使用される。
font-lock-doc-face: コード内のドキュメント文字列にたいして使用される。デフォルトでは、font-lock-string-faceを継承する。
font-lock-negation-char-face: 見逃されやすい否定文字にたいして使用される。

23.6.8 構文的なFont Lock

構文的フォント表示(syntactic fontification)は、構文的に関連性のあるテキストを探してハイライトするために、構文テーブル(syntax table: 構文テーブルを参照)を使用します。有効な場合は、検索ベースフォント表示に先立ち実行されます。以下で説明する変数font-lock-syntactic-face-function,は、どの構文的構造をハイライトするかを決定します。構文的フォント表示に影響を与える変数が、いくつかあります。font-lock-defaultsのために、それらをセットするべきです(Font Lockの基礎を参照)。

Font Lockモードが一連のテキストにたいして構文的フォント表示を処理するときは、常にsyntax-propertize-functionで指定される関数を最初に呼び出します。メジャーモードは、特別なケースではsyntax-tableテキストプロパティを適用してバッファーの構文テーブルをオーバーライドするために、これを使用することができます。構文プロパティを参照してください。

Variable: font-lock-keywords-only: この変数の値が非nilの場合、Font Lockは構文的フォント表示を行わず、font-lock-keywordsにもとづく検索ベースフォント表示だけを行う。これは通常、font-lock-defaults内のkeywords-only要素にもとづき、Font Lockモードによりセットされる。

Variable: font-lock-syntax-table: この変数は、コメントと文字列のフォント表示に使用するための構文テーブルを保持する。これは通常、font-lock-defaults内のsyntax-alist要素にもとづき、Font Lockモードによりセットされる。この値がnilの場合、構文的フォント表示は、バッファーの構文テーブル(関数syntax-tableがリターンする構文テーブル。see section 構文テーブルの関数を参照)を使用する。

Variable: font-lock-syntactic-face-function

この変数が非nilの場合、それは与えられた構文的要素にどのフェイスを使用するかを決定する関数であること。この値は通常、font-lock-defaults内のother-vars要素を通じてセットされる。

この関数は1つの引数で呼び出され、parse-partial-sexpがリターンするポイントの状態をパースして、フェイスをリターンすべきである。コメントにたいしてはfont-lock-comment-face、文字列にたいしてはfont-lock-string-faceが、リターンされるデフォルト値である(Font Lockのためのフェイスを参照)。

23.6.9 複数行のFont Lock構造

通常は、font-lock-keywordsの要素は複数行にわたるマッチを行うべきではありません。それらの動作に信頼性はありません。なぜなら、Font Lockは通常はバッファーのごく一部をスキャンするので、そのスキャンが開始される行境界をまたがる複数行構造を見逃しかねないからです(スキャンは通常、行頭から開始される)。

ある要素にたいして、複数行構造にたいするマッチを正しく機能させるには、2つの観点があります。それは識別(identification)の補正と、再ハイライト(rehighlighting)の補正です。1つ目は、Font Lockがすべての複数行構造を探すことを意味します。2つ目は、複数行構造が変更されたとき、たとえば以前は複数行構造の一部だったテキストが、複数行構造から除外されたときに、関連するすべてのテキストをFont Lockに正しく再ハイライトさせることを意味します。これら2つの観点は密接に関連しており、一方を機能させることがもう一方を機能させるようなことが多々あります。しかし、信頼性のある結果を得るためには、これら2つの観点双方にたいして、明示的に注意しなければなりません。

複数行構造の識別を確実に補正するには、3つの方法があります:

スキャンされるテキストが複数行構造の途中で開始、または終了することがないように識別を行いスキャンを拡張する関数を、font-lock-extend-region-functionsに追加する。
同様に、スキャンされるテキストが複数行構造の途中で開始、または終了することがないようスキャンを拡張するために、font-lock-fontify-region-functionフックを使用する。
複数行構造がバッファーに挿入されたとき(または挿入後、Font Lockがハイライトを試みる前の任意のタイミングで)、何らかの方法によりそれを正しく認識して、Font Lockが複数行構造の途中で開始、または終了しないよう指示するfont-lock-multilineでそれをマークする。

複数行構造の再ハイライトを行うには、3つの方法があります:

その構造にたいして、正しくfont-lock-multilineを配する。これにより、その構造の一部が変更された場合は、構造全体が再ハイライトされるだろう。あるケースにおいては、それを参照するfont-lock-multiline変数をセットすることにより、これを自動的に行うことができる。
jit-lock-contextuallyを確実にセットして、それが行う処理に委ねる。これにより、実際の変更に続いて構造の一部だけが、若干の遅延の後に再ハイライトされるだろう。これは、複数行構造のさまざまな箇所のハイライトが、後続行のテキストに依存しない場合のみ機能する。jit-lock-contextuallyはデフォルトでアクティブなので、これは魅力的な解決策になり得る。
その構造上に、正しくjit-lock-defer-multilineを配する。これは、jit-lock-contextuallyが使用された場合のみ機能し、再ハイライト前に同様の遅延を伴うが、font-lock-multilineのように後続行に依存する箇所のハイライトも処理する。

23.6.9.1 複数行のFont Lock

複数行構造のFont Lockを確実に再ハイライトする方法の1つは、それらをテキストプロパティfont-lock-multilineにputする方法です。複数行構造の一部であるようなテキストにたいしては、このプロパティが存在し、値が非nilであるべきです。

Font Lockがテキスト範囲をハイライトしようとする際は、それらがfont-lock-multilineプロパティでマークされたテキストにならないように、まず必要に応じて範囲の境界を拡張します。それから、その範囲のすべてのfont-lock-multilineを削除して、ハイライトします。ハイライト指定(大抵はfont-lock-keywords)は、適宜このプロパティを毎回再インストールしなければなりません。

警告: ハイライトが低速になるので、大きなテキスト範囲にたいしてfont-lock-multilineを使用してはならない。

Variable: font-lock-multiline

font-lock-multiline変数がtにセットされている場合、Font Lockは自動的に複数行構造にたいしてfont-lock-multilineプロパティの追加を試みる。しかし、これによりFont Lockが幾分遅くなるので、普遍的解ではない。これは、何らかの複数行構造を見逃したり、必要なものより多く、または少なくプロパティをセットするかもしれない。

matcherが関数であるような要素は、たとえ少量のサブパート(subpart)だけがハイライトされるような場合でも、submatch 0(訳注:正規表現の後方参照においてsubmatch 0はマッチした文字列全体を指す)が関連する複数行構造全体を確実に網羅するようにすべきである。単に手動でfont-lock-multilineを追加するのが容易な場合も多々ある。

The font-lock-multiline property is meant to ensure proper refontification; it does not automatically identify new multiline constructs. Identifying them requires that Font Lock mode operate on large enough chunks at a time. This will happen by accident on many cases, which may give the impression that multiline constructs magically work. If you set the font-lock-multiline variable non-nil, this impression will be even stronger, since the highlighting of those constructs which are found will be properly updated from then on. But that does not work reliably.

信頼性を保ち複数行構造を見つけるためには、Font Lockが調べる前にテキストのfont-lock-multilineプロパティを手動で配すか、font-lock-fontify-region-functionを使用しなければなりません。

23.6.9.2 バッファー変更後のリージョンのフォント化

バッファーが変更されたとき、Font Lockが再フォント表示するリージョンは、デフォルトではその変更に関連する、最小の行全体からなるシーケンスです。これはほとんどの場合は良好に機能しますが、うまく機能しないとき(たとえば、その変更がそれより前の行のテキストの構文的な意味を変更してしまうとき)もあります。

以下の変数をセットすることにより、再フォント表示するリージョンを拡張(または縮小さえ)することができます:

Variable: font-lock-extend-after-change-region-function

このバッファーローカル変数はnil、またはFont Lockモードにたいしてスキャンしてフォント表示すべきリージョンを決定するために呼び出される関数である。

この関数には、標準的なbegとend、およびafter-change-functionsのold-len(フックの変更を参照)という、3つのパラメーターが渡される。この関数はフォント表示するリージョンのバッファー位置の開始と終了(この順で)からなるコンスセル、またはnil(標準的な方法でリージョンを選択することを意味する)のいずれかをリターンすべきである。この関数は、ポイント位置、match-data、カレントのナローイングを保つ必要がある。これがリターンするリージョンは、行の途中で開始、または終了するかもしれない。

この関数はバッファーを変更するたびに呼び出されるので、有意に高速であること。

23.7 コードの自動インデント

プログラミング言語のメジャーモードにとって、自動的なインデントの提供は、重要な機能です。これには2つのパートがあります。1つ目は正しい行のインデントが何か、そして2つ目はいつ行を再インデントするかの判断です。デフォルトでは、electric-indent-charsに含まれる文字(デフォルトでは改行のみ)をタイプしたとき、Emacsは常に行を再インデントします。メジャーモードは、その言語の構文に合わせて、electric-indent-charsに文字を追加できます。

正しいインデントの決定は、indent-line-functionによりEmacs内で制御されます(メジャーモードが制御するインデントを参照)。いくつかのモードでは、右へのインデントは信頼性がないことが知られています。これは通常、複数のインデントが有効だが、それぞれが異なる意味をもつので、インデント自体が重要だからです。そのような場合、そのモードは行が常にユーザーの望み通り再インデントされないことを念押しするために、electric-indent-inhibitをセットするべきです。

よいインデント関数の記述は難しく、その広範な領域において、未だ黒魔術の域を脱していません。メジャーモード作者の多くは、単純なケース(たとえば前のテキスト行のインデントとの比較)にたいして機能する、単純な関数の記述からスタートすることでしょう。実際には行ベースではないほとんどのプログラミング言語にたいして、これは貧弱なスケールになりがちです。そのような関数にたいして、より多様な状況を処理するような改良を行うと、関数はより一層複雑になり、最終的な結果は誰にも触れようとする気を起こさせない、巨大で複雑な保守不可能のインデント関数になる傾向があります。

よいインデント関数は通常、その言語の構文に応じて、実際にテキストをパースする必要があるでしょう。幸運なことに、このテキストパースはコンパイラーが要するほど詳細である必要はないでしょうが、その一方でインデントコードに埋め込まれたパーサーは、構文的に不正なコードにたいして、コンパイラーより幾分寛容な振る舞いを求められるでしょう。

Good maintainable indentation functions usually fall into two categories: either parsing forward from some safe starting point until the position of interest, or parsing backward from the position of interest. Neither of the two is a clearly better choice than the other: parsing backward is often more difficult than parsing forward because programming languages are designed to be parsed forward, but for the purpose of indentation it has the advantage of not needing to guess a safe starting point, and it generally enjoys the property that only a minimum of text will be analyzed to decide the indentation of a line, so indentation will tend to be less affected by syntax errors in some earlier unrelated piece of code. Parsing forward on the other hand is usually easier and has the advantage of making it possible to reindent efficiently a whole region at a time, with a single parse.

インデント関数をスクラッチから記述するよりも、既存のインデント関数の試用と再利用、または一般的なインデントエンジンに委ねるほうが優る場合が、しばしばあります。しかし、そのようなエンジンは悲しむべきほど少数しかありません。CCモードのインデントコード(C、C++、Java、Awk、およびその類のモードが使用)は年月を経てより一般化されてきているので、あなたの言語にこれらの言語と何らかの相似点があるなら、このエンジンの使用を試みるかもしれません。もう一方のSMIEはLispのsexp精神によるアプローチを採用して、それを非Lisp言語に適応します。

23.7.1 SMIE: 無邪気なインデントエンジン

SMIE is a package that provides a generic navigation and indentation engine. Based on a very simple parser using an operator precedence grammar, it lets major modes extend the sexp-based navigation of Lisp to non-Lisp languages as well as provide a simple to use but reliable auto-indentation.

演算子順位文法は、コンパイラー内で使用されるより一般的なパーサーと比較すると、非常に原始的なパーステクノロジーです。このパーサーには次のような特徴があります。このパーサーのパース能力は非常に限定的で、大概は構文エラーを検出できません。しかし、アルゴリズム的に前方パースと同様に後方パースを効果的に行うことが可能です。実際にそれはSMIEが後方パースにもとづくインデントを使用でき、forward-sexpとbackward-sexpの両方の機能を提供できるとともに、特別な努力を要さずに構文的に不正なコードにたいして自然に機能するであろうことを意味します。欠点は、ほとんどのプログラミング言語は、少なくとも何らかの特別なトリック(非力なパーサーの使用を参照)で再分類しなければ、SMIEを使用して正しくパースできないことも意味するからです。

23.7.1.1 SMIEのセットアップと機能

SMIEは、構造的な操作と、コードの構造的構造にもとづくその他さまざまな機能、特に自動インデントにたいするワンストップショップ(一カ所で必要な全ての買い物ができること、またはそのような場所)であることを意図しています。メインのエントリーポイントはsmie-setupで、これは通常メジャーモードセットアップの間に呼び出される関数です。

Function: smie-setup grammar rules-function &rest keywords

SMIEの操作とインデントをセットアップする。grammarはsmie-prec2->grammarにより生成される文法テーブル(grammar table)、rules-functionはsmie-rules-functionで使用されるインデントルールのセット、keywordsは追加の引数であり以下のキーワードを含むことができる:

:forward-token fun: 使用する前方lexer(lexer=lexical analyzer: 字句解析プログラム)を指定する。
:backward-token fun: 使用する後方lexerを指定する。

この関数を呼び出せば、forward-sexp、backward-sexp、transpose-sexpsのようなコマンドが、すでに構文テーブルにより処理されている単なるカッコのペアー以外の、構造的な要素を正しく扱うことができるようになります。たとえば、与えられた文法が十分に明快ならば、transpose-sexpsはその言語の優先順位のルールを考慮して、+演算子の2つの引数を正しく入れ替えることができます。

Calling smie-setup is also sufficient to make TAB indentation work in the expected way, extends blink-matching-paren to apply to elements like begin...end, and provides some commands that you can bind in the major mode keymap.

Command: smie-close-block: このコマンドは、もっとも最近オープンされた(まだクローズされていない)ブロックをクローズする。

Command: smie-down-list &optional arg: このコマンドはdown-listと似ているが、begin...endのようなカッコ以外のネストされたトークンにも注意を払う。

23.7.1.2 演算子順位文法

SMIEの演算子順位文法は、各トークンにたいしてシンプルに左優先(left-precedence)と右優先(right-precedence)という順位ペアーを与えます。トークンT1の右優先が、トークンT2の左優先より小さい場合は、T1 < T2であると言うことにしましょう。これを解読するには、<をカッコの一種だとみなすのがよい方法です。... T1 something T2 ...を見つけたら、これは... T1 something) T2 ...ではなく... T1 (something T2 ...とパースされるべきです。... T1 something) T2 ...と解釈するのは、T1 > T2を見つけた場合でしょう。T1 = T2を見つけた場合、それはトークンT2とその後のトークンT1が同じ構文構成にあり、通常は"begin" = "end"を得ます。このような優先順位のペアーは、2項演算子(infix operator)、カッコのようなネストされたトークン、およびその他多くのケースにたいして左結合(left-associativity)や右結合(right-associativity)を表現するのに十分です。

Function: smie-prec2->grammar table: この関数は、prec2文法tableを引数にとり、smie-setupで使用するのに適したalistをリターンする。prec2文法tableは、それ自体が以下の関数のいずれかによりビルドされることを意図している。

Function: smie-merge-prec2s &rest tables: この関数は、複数のprec2文法tablesを、新たなprec2テーブルにマージする。

Function: smie-precs->prec2 precs: この関数は、順位テーブルprecsからprec2テーブルをビルドする。precsは優先順(たとえば"+"は"*"より前にくる)にソートされたリストで、要素は(assoc op ...)の形式であること。ここで、opは演算子として振る舞うトークン、assocはそれらの結合法則であり、left、right、assoc、nonassocのいずれかである。与えられた要素内のすべての演算子は、同じ優先レベルと結合法則を共有する。

Function: smie-bnf->prec2 bnf &rest resolvers

この関数により、BNF記法を使用した文法を指定することができる。これは、その文法のbnf表記と、同様に競合解決ルールresolversを受け取り、prec2テーブルをリターンする。

bnfは(nonterm rhs1 rhs2 ...)という形式の非終端定義で、各rhsは終端記号(トークンとも呼ばれる)、または非終端記号の(空でない)リストである。

すべての文法が許される訳ではない:

rhsに空のリストは指定できない(いずれにせよSMIEは空文字列にマッチさせるためにすべての非終端記号を許すので、空リストが必要になることは決してない)。
rhsの後に連続する2つの非終端記号は指定できない。非終端記号の各ペアーは終端記号(もしくはトークン)で区切られる必要がある。これは、演算子順位文法の基本的な制約である。

さらに、競合が発生し得る:

リターンされるprec2テーブルはトークンのペアー間の制約を保持し、与えられた任意のペアーはT1 < T2、T1 = T2、T1 > T2のいずれかのうち、ただ1つの制約を与えることができる。
トークンは、opener(開きカッコに似た何か)、closer(閉じカッコのようなもの)、またはこれら2つのいずれでもないneither(2項演算子や"else"のようなinnerトークン)である。

順位の競合は、resolversを通じて解決され得る。これはprecsテーブル(smie-precs->prec2を参照)のリストである。それぞれの順位競合にたいして、これらのprecsテーブルが特定の制約を指定している場合は、かわりにこの制約により競合が解決され、それ以外は競合する制約のうち任意の1つが報告され、他は単に無視される。

23.7.1.3 言語の文法の定義

ある言語にたいしてSMIE文法を定義する通常の方法は、順位のテーブルを保持する新たなグローバル変数を定義して、BNFルールのセットを与える方法です。たとえば、小規模なPascal風言語の文法定義は、以下のようになるでしょう:

(require 'smie)
(defvar sample-smie-grammar
  (smie-prec2->grammar
   (smie-bnf->prec2

    '((id)
      (inst ("begin" insts "end")
            ("if" exp "then" inst "else" inst)
            (id ":=" exp)
            (exp))
      (insts (insts ";" insts) (inst))
      (exp (exp "+" exp)
           (exp "*" exp)
           ("(" exps ")"))
      (exps (exps "," exps) (exp)))

    '((assoc ";"))
    '((assoc ","))
    '((assoc "+") (assoc "*")))))

注意すべき点がいくつかあります:

上記の文法は、関数呼び出しの構文に明示的に言及していない。SMIEは識別子、対応がとれたカッコ(balanced parentheses)、またはbegin ... endブロックのようなsexpの任意のシーケンスが、どこに、どのように出現しても、自動的にそれを許容するだろう。
文法カテゴリーidは、右側に何ももたない。これは、idが空文字列だけにマッチ可能なことを意味しない。なぜなら上述のように、任意のsexpシーケンスは、どこに、どのような方法でも出現するからである。
BNF文法では非終端記号が連続して出現し得ないので、終端記号として作用するトークンを正しく扱うのが困難なので、上述の文法では、SMIEが容易に扱える";"を、セパレーター(separator)ステートメントのかわりとして扱っている。
シーケンス内で使用される、(上記の","や";"のような)セパレーターは、BNFルールでは(foo (foo "separator" foo) ...)のように定義するのが最善である。これは、順位の競合を生成するが、明示的に(assoc "separator")を与えることにより解決される、
SMIEは、構文テーブル(syntax table)内でカッコ構文(paren syntax)をもつようにマークされたー任意の文字をペアーにするだろうから、("(" exps ")")ルールにカッコをペアーにする必要はなかった。(expsの定義と併せて)このルールはかわりに、","がカッコの外に出現すべきではないことを明確にする。
競合解決のためのprecsテーブルは、単一のテーブルより複数のテーブルをもつほうが、可能な場合は文法のBNF部分が関連する順位を指定できるので、優れている。
leftまたはrightを選択すること優るという明白な理由がない場合は、通常はassocを使用して演算子を結合演算子(associative)とマークするほうが優れている。この理由により、上述の"+"と"*"は、たとえその言語がそれらを形式上は左結合(left associative)と定義していても、assocとして定義されている。

23.7.1.4 トークンの定義

SMIEには、事前定義された字句解析プログラムが付属しており、それは次の方法で構文テーブルを使用します: 文字の任意のシーケンスは、トークンとみなせる単語構文(word syntax)、またはシンボル構文(symbol syntax)をもち、句読点構文(punctuation syntax)をもつ任意の文字シーケンスもトークンとみなされます。このデフォルトのlexerは、開始ポイントとして適している場合が多々ありますが、任意の与えられた言語にたいして、実際に正しいことは稀です。たとえば、これは"2,+3"が3つのトークン"2"、",+"、"3"から構成されていると判断するでしょう。

あなたの言語のlexerルールをSMIEにたいして説明するためには、次のトークンをfetchする関数と、前のトークンをfetchする関数の、2つの関数が必要になります。これらの関数は通常、最初に空白文字とコメントをスキップして、その後に次のテキストchunk(塊)を調べて、それが特別なトークンか確認します。これは通常、バッファーから単に抽出された文字列ですが、あなたが望む他の何かでも構いません。たとえば:

(defvar sample-keywords-regexp
  (regexp-opt '("+" "*" "," ";" ">" ">=" "<" "<=" ":=" "=")))

(defun sample-smie-forward-token ()
  (forward-comment (point-max))
  (cond
   ((looking-at sample-keywords-regexp)
    (goto-char (match-end 0))
    (match-string-no-properties 0))
   (t (buffer-substring-no-properties
       (point)
       (progn (skip-syntax-forward "w_")
              (point))))))

(defun sample-smie-backward-token ()
  (forward-comment (- (point)))
  (cond
   ((looking-back sample-keywords-regexp (- (point) 2) t)
    (goto-char (match-beginning 0))
    (match-string-no-properties 0))
   (t (buffer-substring-no-properties
       (point)
       (progn (skip-syntax-backward "w_")
              (point))))))

これらのlexerがカッコの前にあるとき、空文字列をリターンする方法に注目してください。これは、SMIEが構文テーブル内で定義されているカッコにたいして、自動的に配慮するからです。より厳密には、lexerがnil、または空文字列をリターンした場合、SMIEは構文テーブルにしたがい、対応するテキストをsexpとして処理します。

23.7.1.5 非力なパーサーの使用

SMIEが使用するパーステクニックは、異なるコンテキストでトークンが異なる振る舞いをすることを許しません。ほとんどのプログラミング言語にたいして、これは順位の競合によりBNF文法を変換するとき明らかになります。

その文法を若干異なるように表現することにより、これらの競合を回避できる場合があります。たとえばModula-2にたいしては、以下のようなBNF文法をもつのが自然に思えるかもしれません:

  ...
  (inst ("IF" exp "THEN" insts "ELSE" insts "END")
        ("CASE" exp "OF" cases "END")
        ...)
  (cases (cases "|" cases)
         (caselabel ":" insts)
         ("ELSE" insts))
  ...

しかし、これは"ELSE"にたいする競合を生み出すでしょう。その一方でIFルールは、(他の多くのものの中でも特に)"ELSE" = "END"を暗示します。しかしその一方では、"ELSE"はcases内に出現しますが、casesは"END"の左に出現するので、わたしたちは"ELSE" > "END"も得ることになります。これは、以下を使用して解決できます:

  ...
  (inst ("IF" exp "THEN" insts "ELSE" insts "END")
        ("CASE" exp "OF" cases "END")
        ("CASE" exp "OF" cases "ELSE" insts "END")
        ...)
  (cases (cases "|" cases) (caselabel ":" insts))
  ...

または

  ...
  (inst ("IF" exp "THEN" else "END")
        ("CASE" exp "OF" cases "END")
        ...)
  (else (insts "ELSE" insts))
  (cases (cases "|" cases) (caselabel ":" insts) (else))
  ...

文法を書き換えによる競合の解決には欠点があります。なぜなら、SMIEはその文法がコードの論理的構造を反映すると仮定するからです。そのため、BNFと意図する抽象的構文木の関係を密接に保つことが望まれます。

注意深く考慮した後に、これらの競合は深刻ではなく、smie-bnf->prec2のresolvers引数を通じて解決する決心する場合もあるでしょう。これは通常、その文法が単に不明瞭だからです。その文法により記述されるプログラムセットは競合の影響を受けませんが、それらのプログラムにたいする唯一の方法はパースだけです。'((assoc "|"))のようなリゾルバ(resolver: 解決するもの)を追加したいと望むような場合、通常それはセパレーターと2項結合演算子にたいするケースです。これが発生し得る他のケースは、'((assoc "else" "then"))を使用するような場合における、古典的なぶら下がりelse問題dangling else problemです。これは実際に競合があり解決不能だが、実際のところ問題が発生しそうにないケースにたいしても、発生し得ます。

最後に、多くのケースでは、すべての文法再構築努力にも関わらず、いくつかの競合が残るでしょう。しかし失望しないでください。パーサーをより賢くすることはできませんが、あなたの望むようにlexerをスマートにすることは可能です。その方法は、競合が発生したら競合を引き起こしたトークンを調べて、それらのうちの1つを2つ以上の異なるトークンに分割する方法です。たとえば、トークン"begin"にたいする互換性のない2つの使用を文法が区別する必要があり、見つかった"begin"の種類により、lexerに異なるトークン(たとえば"begin-fun"と"begin-plain")をリターンさせる場合です。これはlexerにたいして、異なるケースを区別する処理を強い、そのためにlexerは特別な手がかりを見つけるために、周囲のテキストを調べる必要があるでしょう。

23.7.1.6 インデントルールの指定

提供された文法にもとづき、他に特別なことを行わなくても、SMIEは自動的なインデントを提供できるでしょう。しかし実際には、このデフォルトのインデントスタイルでは、恐らく十分ではありません。多くの異なる状況において、これを微調整したいと思うかもしれません。

SMIEのインデントは、インデントルールは可能な限りローカルであるべきという考えにもとづきます。バーチャルインデント(virtual indentation)という考えによって、この目的を達成します。これは、特定のプログラムポイント(program point)は行頭にバーチャルインデントがある場合は、それをもつだろう、という発想です。もちろん、そのプログラムポイントが正に行頭にある場合は、そのプログラムポイントのバーチャルインデントは、プログラムポイントのカレントのインデントです。しかしそうでない場合は、SMIEがそのポイントのバーチャルインデントを計算するために、インデントアルゴリズムを使用します。ところで実際には、あるプログラムポイントのバーチャルインデントは、その前に改行を挿入した場合にプログラムポイントがもつであろうインデントと等しい必要はありません。これが機能する方法を確認するためには、Cにおける{の後のSMIEのインデントルールは、{がインデントする行自体にあるか、あるいは前の行の終端にあるかを配慮しないことが挙げられます。かわりに、これらの異なるケースは、{の前のインデントを決定するインデントルール内で処理されます。

他の重要な考え方として、parentの概念があります。あるトークンparentは、周囲にある直近の構文構造の代表トークン(head token)です。たとえば、elseのparentは、それが属するifであり、ifのparentは周囲を取り囲む構造の先導トークン(lead token)です。コマンドbackward-sexpは、あるトークンからトークンのparentにジャンプしますが、注意点がいくつかあります。opener(ifのような、ある構造を開始するトークン)にたいしては、他のトークンではそのトークンの後のポイントから開始する必要があるのにたいして、opnerではそのトークンの前のポイントから開始する必要があります。backward-sexpはparentトークンがそのトークンのopenerの場合はparentトークンの前のポイントで停止し、それ以外ではparentトークンの後のポイントで停止します。

SMIEのインデントルールは、2つの引数methodとargをとる関数により指定されます。ここでargの値と期待されるリターン値は、methodに依存します。

methodは、以下のいずれかを指定できます:

:after: この場合、argはトークンであり、関数はargの後に使用するインデントにたいするoffsetをリターンすべきである。
:before: この場合、argはトークンであり、関数はarg自体に使用するインデントのoffsetをリターンすべきである。
:elem: この場合、関数は関数の引数に使用するインデントのオフセット(argがargの場合)、または基本的のインデントステップ(argがbasicの場合)、のいずれかをリターンすべきである。
:list-intro: この場合、argはトークンであり、関数はそのトークンの後が単一の式ではなく、(任意のトークンにより区切られない)式のリストが続く場合は非nilをリターンすべきである。

argがトークンのとき、関数はそのトークンの直前のポイントで呼び出されます。リターン値nilは常にデフォルトの振る舞いへのフォールバックを意味するので、関数は期待した引数でないときはnilをリターンするべきです。

offsetは、以下のいずれかを指定できます:

nil: デフォルトのインデントルールを使用する。
(column . column): 列columnにインデントする。
number: 基本トークン(base token: :afterにたいするカレントトークンであり、かつ:beforeにたいしてparentであるようなトークン)にたいして相対的な、numberによるオフセット。

23.7.1.7 インデントルールにたいするヘルパー関数

SMIEは、インデントを決定する関数内で使用するために特別にデザインされた、さまざまな関数を提供します(これらの関数のうちのいくつかは、異なるコンテキスト内で使用された場合は中断する)。これらの関数はすべて、プレフィックスsmie-rule-で始まります。

Function: smie-rule-bolp: カレントトークンが行の先頭にある場合は、非nilをリターンする。

Function: smie-rule-hanging-p: カレントトークンがhanging(ぶら下がり)の場合は、非nilをリターンする。トークンがその行の最後のトークンであり、他のトークンが先行する場合、そのトークンはhangingである。行に単独のトークンはhangingではない。

Function: smie-rule-next-p &rest tokens: 次のトークンがtokens内にある場合は、非nilをリターンする。

Function: smie-rule-prev-p &rest tokens: 前のトークンがtokens内にある場合は、非nilをリターンする。

Function: smie-rule-parent-p &rest parents: カレントトークンのparentがparents内にある場合は、非nilをリターンする。

Function: smie-rule-sibling-p: カレントトークンのparentが実際はsibling(兄弟)の場合は、非nilをリターンする。たとえば","のparentが直前の","のような場合が該当する。

Function: smie-rule-parent &optional offset: カレントトークンをparentとアライン(align: 桁揃え)するための適切なオフセットをリターンする。offsetが非nilの場合、それは追加オフセットとして適用される整数であること。

Function: smie-rule-separator method

セパレーター(separator)としてカレントトークンをインデントする。

ここでのセパレーターは、周囲を取り囲む何らかの構文構造内でさまざまな要素を区切ることを唯一の目的とするトークンであり、それ自体は何も意味をもたないトークン(通常は抽象構文木内でノードとして存在しない)を意味する。

このようなトークンは結合構文をもち、その構文的parentと密に結び付けられることが期待される。典型的な例としては引数リスト内の","(カッコで括られた内部)、または命令文シーケンス内の";"({...}やbegin...endで括られたブロックの内部)が挙げられる。

method should be the method name that was passed to smie-rules-function.

23.7.1.8 インデントルールの例

以下は、インデント関数の例です:

(defun sample-smie-rules (kind token)
  (pcase (cons kind token)
    (`(:elem . basic) sample-indent-basic)
    (`(,_ . ",") (smie-rule-separator kind))
    (`(:after . ":=") sample-indent-basic)
    (`(:before . ,(or `"begin" `"(" `"{")))
     (if (smie-rule-hanging-p) (smie-rule-parent)))
    (`(:before . "if")
     (and (not (smie-rule-bolp)) (smie-rule-prev-p "else")
          (smie-rule-parent)))))

注意すべき点がいくつかあります:

最初のcaseは、使用する基本的なインデントの増分を示す。sample-indent-basicがnilの場合、SMIEはグローバルセッティングsmie-indent-basicを使用する。メジャーモードがかわりにsmie-indent-basicをバッファーローカルにセットするかもしれないが、これは勧められない。
トークン","にたいするルールにより、カンマセパレーターが行頭にある場合に、SMIEをより賢明に振る舞わせようとしている。これはセパレーターのインデントを解除(outdent)、カンマの後のコードにアラインされるよう試みる。たとえば:
```
x = longfunctionname (
        arg1
      , arg2
    );
```
":="の後のインデントのルールは、そうしなければSMIEが":="を2項演算子として扱い、左の引数に併せて右の引数をアラインするであろうから、このルールが存在する。
"begin"の前のインデントのルールは、バーチャルインデントの使用例である。このルールは"begin"がhangingのときだけ使用され、これは"begin"が行頭にないときのみ発生し得る。そのため、これは"begin"自体のインデントには使用されないが、この"begin"に関連する何かをインデントするときだけ使用される。このルールは、具体的には以下のフォームを:
```
    if x > 0 then begin
            dosomething(x);
        end
```
以下に変更する
```
    if x > 0 then begin
        dosomething(x);
    end
```
"if"の前のインデントのルールは"begin"のインデントルールと似ているが、ここでの目的は"else if"を1単位として扱うことにあり、それにより各テストより右にインデントされずに、一連のテストにアラインされる。この関数はsmie-rule-bolpをテストして、"if"が別の行にないときだけこれを行う。
"else"が、それの属する"if"にたいして常にアラインされ、かつそれが常に行頭であるることが判っている場合は、より効果的なルールを使用できる:
```
((equal token "if")
 (and (not (smie-rule-bolp))
      (smie-rule-prev-p "else")
      (save-excursion
        (sample-smie-backward-token)
        (cons 'column (current-column)))))
```
この式の利点は、これがシーケンスの最初の"if"まで戻ってすべてをやり直すのではなく、前の"else"のインデントを再利用することである。

23.7.1.9 インデントのカスタマイズ

SMIEにより提供されるインデントを使用するモードを使っている場合は、好みに合わせてインデントをカスタマイズできます。これはモードごと(オプションsmie-configを使用)、またはファイルごと(ファイルローカル変数指定内で関数smie-config-localを使用)に行うことができます。

User Option: smie-config: このオプションにより、モードごとにインデントをカスタマイズできる。これは(mode . rules)という形式の要素をもつalistである。rulesの正確な形式については、変数のドキュメントを参照のこと。しかし、コマンドsmie-config-guessを使用したほうが、より簡単に見つけられるかもしれない。

Command: smie-config-guess: このコマンドは、好みのスタイルのインデントを生成する、適切セッティングの解決を試みる。あなたのスタイルでインデントされたファイルをvisitしているときに、単にこのコマンドを呼び出せばよい。

Command: smie-config-save: smie-config-guessを使用した後にこのコマンドを呼び出すと、将来のセッション用にセッティングを保存する。

Command: smie-config-show-indent &optional move: このコマンドは、カレント行のインデントに使用されているルールを表示する。

Command: smie-config-set-indent: このコマンドは、カレント行のインデントに合わせて、ローカルルールを追加する。

Function: smie-config-local rules: この関数は、カレントバッファーにたいするインデントルールとして、rulesを追加する。これらのルールは、smie-configオプションにより定義された、任意のモード固有ルールに追加される。特定のファイルにたいしてカスタムインデントルールを指定するには、eval: (smie-config-local '(rules))の形式のエントリーを、そのファイルのローカル変数に追加する。

23.8 Desktop Saveモード

Desktop Saveモードとは、あるセッションから別のセッションへ、Emacs状態を保存する機能です。Desktop Saveモードの使用に関するユーザーレベルのコマンドについては、GNU Emacsマニュアルに記載されています(Saving Emacs Sessions in the GNU Emacs Manualを参照)。バッファーでファイルをvisitしているモードでは、この機能を使うために何も行う必要はありません。

ファイルをvisitしていないバッファーについて状態を保存するには、そのメジャーモードがバッファーローカル変数desktop-save-bufferを非nil値にバインドしなければなりません。

Variable: desktop-save-buffer

このバッファーローカル変数が非nilの場合は、デスクトップ保存時にそのバッファー状態がdesktopファイルに保存される。値が関数の場合、その関数はデスクトップ保存時に引数desktop-dirnameで呼び出され、関数が呼び出されたバッファーの状態とともに、関数の値がdesktopファイルに保存される。補助的な情報の一部としてファイル名がリターンされたとき、それらは以下を呼び出してフォーマットされるべきである

(desktop-file-name file-name desktop-dirname)

ファイルをvisitしていないバッファーがリストアされるようにするには、その初を行う関数をメジャーモードが定義しなければならず、その関数はalist desktop-buffer-mode-handlersにリストされなければならない。

Variable: desktop-buffer-mode-handlers

以下を要素にもつalistである

(major-mode . restore-buffer-function)

関数restore-buffer-functionは、以下の引数リストで呼び出されるだろう

(buffer-file-name buffer-name desktop-buffer-misc)

この関数は、リストアされたバッファーをリターンすべきである。ここで、desktop-buffer-miscは、オプションでdesktop-save-bufferにバインドされる関数によりリターンされる値である。

24 ドキュメント

GNU Emacsには便利なビルトインのヘルプ機能があり、それらのほとんどは、関数や変数のドキュメント文字列に付属するドキュメント文字列の情報が由来です。このチャプターでは、Lispプログラムからドキュメント文字列にアクセスする方法について説明します。

ドキュメント文字列のコンテンツは、ある種の慣習にしたがうべきです。特に、最初の行は、その関数または変数を簡単に説明する1つ、または2つの完全なセンテンスであるべきです。よいドキュメント文字列を記述する方法については、ドキュメント文字列のヒントを参照してください。

Emacs向けのドキュメント文字列は、Emacsマニュアルと同じものではないことに注意してください。マニュアルは、Texinfo言語で記述された独自のソースファイルをもちます。それにたいしドキュメント文字列は、それが適用される関数および変数の定義内で指定されます。ドキュメント文字列をコレクションしても、それはマニュアルとしては不十分です。なぜなら、よいマニュアルとは、そのやり方でまとめられたものではなく、議論のトピックという観点によりまとめられているからです。

ドキュメント文字列を表示するコマンドについては、Help in The GNU Emacs Manualを参照してください。

24.1 ドキュメントの基礎		ドキュメント文字列が定義、格納される場所。
24.2 ドキュメント文字列へのアクセス		Lispプログラムがドキュメント文字列にアクセスする方法。
24.3 ドキュメント内でのキーバインディングの置き換え		カレントキーバインディングの置き換え。
24.4 Text Quoting Style		Quotation marks in doc strings and messages.
24.5 ヘルプメッセージの文字記述		非プリント文字やキーシーケンスをプリント可能な記述にする。
24.6 ヘルプ関数		Emacsヘルプ機能により使用されるサブルーチン。

24.1 ドキュメントの基礎

ドキュメント文字列は、テキストをダブルクォート文字で囲んだ、文字列にたいするLisp構文を使用して記述されます。実はこれは実際のLisp文字列です。関数または変数の定義内の適切な箇所に文字列があると、それは関数または変数のドキュメントの役割を果たします。

関数定義(lambdaやdefunフォーム)の中では、ドキュメント文字列は引数リストの後に指定され、通常は関数オブジェクト内に直接格納されます。関数のドキュメント文字列を参照してください。関数名のfunction-documentationプロパティに関数ドキュメントをputすることもできます(ドキュメント文字列へのアクセスを参照)。

変数定義(defvarフォーム)の中では、ドキュメント文字列は初期値の後に指定されます。グローバル変数の定義を参照してください。この文字列は、その変数のvariable-documentationプロパティに格納されます。

Emacsがメモリー内にドキュメント文字列を保持しないときがあります。それには、2つの状況があります。1つ目はメモリーを節約するためで、事前ロードされた関数および変数(プリミティブを含む)のドキュメントは、doc-directoryで指定されたディレクトリー内の、DOCという名前のファイルに保持されます(ドキュメント文字列へのアクセスを参照)。2つ目は関数または変数がバイトコンパイルされたファイルからロードされたときで、Emacsはそれらのドキュメント文字列のロードを無効にします(ドキュメント文字列とコンパイルを参照)。どちらの場合も、ある関数にたいしてユーザーがC-h f(describe-function)を呼び出したときなど、Emacsは必要なときだけファイルのドキュメント文字列を照会します。

ドキュメント文字列には、ユーザーがドキュメントを閲覧するときのみ照会されるキーバインディングを参照する、特別なキー置換シーケンス(key substitution sequences)を含めることができます。これにより、たとえユーザーがデフォルトのキーバインディングを変更していても、ヘルプコマンドが正しいキーを表示できるようになります。

オートロードされたコマンド(autoloadを参照)のドキュメント文字列では、これらのキー置換シーケンスは特別な効果をもち、そのコマンドにたいするC-h fにより、オートロードをトリガーします(これは*Help*バッファー内のハイパーリンクを正しくセットアップするために必要となる)。

24.2 ドキュメント文字列へのアクセス

Function: documentation-property symbol property &optional verbatim

この関数は、プロパティproperty配下のsymbolのプロパティリスト内に記録されたドキュメント文字列をリターンする。ほとんどの場合、これはpropertyをvariable-documentationにして、変数のドキュメント文字列の照会に使用される。しかし、カスタマイゼーショングループのような、他の種類のドキュメント照会にも使用できる(が、関数のドキュメントには、以下のdocumentation関数を使用する)。

そのプロパティの値がDOCファイルやバイトコンパイル済みファイルに格納されたドキュメント文字列を参照する場合、この関数はその文字列を照会して、それをリターンする。

プロパティの値がnilや文字列以外で、ファイル内のテキストも参照しない場合は、文字列を取得するLisp式として評価される。

最終的に、この関数はキーバインディングを置換するために、文字列をsubstitute-command-keysに引き渡す(ドキュメント内でのキーバインディングの置き換えを参照)。verbatimが非nilの場合、このステップはスキップされる。

(documentation-property 'command-line-processed
   'variable-documentation)
     ⇒ "Non-nil once command line has been processed"

(symbol-plist 'command-line-processed)
     ⇒ (variable-documentation 188902)

(documentation-property 'emacs 'group-documentation)
     ⇒ "Customization of the One True Editor."

Function: documentation function &optional verbatim

この関数は、functionのドキュメント文字列をリターンする。この関数はマクロ、名前付きキーボードマクロ、およびスペシャルフォームも通常の関数と同様に処理する。

functionがシンボルの場合は、そのシンボルのfunction-documentationプロパティを最初に調べる。それが非nil値をもつなら、その値(プロパティの値が文字列以外の場合は、それを評価した値)がドキュメントとなる。

functionがシンボル以外、あるいはfunction-documentationプロパティをもたない場合、documentationは必要ならファイルを読み込んで、実際の関数定義のドキュメント文字列を抽出する。

最後に、verbatimがnilなら、この関数はsubstitute-command-keysを呼び出す。結果はリターンするための文字列である。

documentation関数は、functionが関数定義をもたない場合は、void-functionエラーをシグナルする。しかし、関数定義がドキュメントをもたない場合は問題ない。その場合、documentationはnilをリターンする。

Function: face-documentation face: この関数は、faceのドキュメント文字列をフェイスとしてリターンする。

以下は、documentationとdocumentation-propertyを使用した例で、いくつかのシンボルのドキュメント文字列を*Help*バッファー内に表示します。

(defun describe-symbols (pattern)
  "Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the *Help* buffer."
  (interactive "sDescribe symbols matching: ")
  (let ((describe-func
         (function
          (lambda (s)

            ;; シンボルの説明をプリントする
            (if (fboundp s)             ; これは関数
                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (commandp s)
                       (let ((keys (where-is-internal s)))
                         (if keys
                             (concat
                              "Keys: "
                              (mapconcat 'key-description
                                         keys " "))
                           "Keys: none"))
                     "Function")

                   (or (documentation s)
                       "not documented"))))

            (if (boundp s)              ; これは変数

                (princ
                 (format "%s\t%s\n%s\n\n" s
                   (if (custom-variable-p s)
                       "Option " "Variable")

                   (or (documentation-property
                         s 'variable-documentation)
                       "not documented")))))))
        sym-list)

    ;; PATTERNにマッチするシンボルのリストを構築
    (mapatoms (function
               (lambda (sym)
                 (if (string-match pattern (symbol-name sym))
                     (setq sym-list (cons sym sym-list))))))

    ;; データを表示
    (help-setup-xref (list 'describe-symbols pattern) (interactive-p))
    (with-help-window (help-buffer)
      (mapcar describe-func (sort sym-list 'string<)))))

describe-symbols関数はaproposのように機能しますが、より多くの情報を提供します。

(describe-symbols "goal")

---------- Buffer: *Help* ----------
goal-column     Option
Semipermanent goal column for vertical motion, as set by …

minibuffer-temporary-goal-position      Variable
not documented

set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.

Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument ARG, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable ‘goal-column’.

(fn ARG)

temporary-goal-column   Variable
Current goal column for vertical motion.
It is the column where point was at the start of the current run
of vertical motion commands.

When moving by visual lines via the function ‘line-move-visual’, it is a cons
cell (COL . HSCROLL), where COL is the x-position, in pixels,
divided by the default column width, and HSCROLL is the number of
columns by which window is scrolled from left margin.

When the ‘track-eol’ feature is doing its job, the value is
‘most-positive-fixnum’.
---------- Buffer: *Help* ----------

Function: Snarf-documentation filename

この関数は、Emacsビルド時の実行可能なEmacsダンプ直前に使用される。これは、ファイルfilename内に格納されたドキュメント文字列の位置を探して、メモリー上の関数定義および変数のプロパティリスト内にそれらの位置を記録する。Emacsのビルドを参照のこと。

Emacsは、emacs/etcディレクトリーから、ファイルfilenameを読み込む。その後、ダンプされたEmacs実行時に、ディレクトリーdoc-directory内の同じファイルを照会する。filenameは通常"DOC"である。

Variable: doc-directory

この変数は、ビルトインおよび事前ロードされた関数および変数のドキュメント文字列を含む、ファイル"DOC"があるべきディレクトリーの名前を保持する。

ほとんどの場合、これはdata-directoryと同一である。実際にインストールしたEmacsではなく、EmacswpeyビルドしたディレクトリーからEmacsを実行したときは、異なるかもしれない。Definition of data-directoryを参照のこと。

24.3 ドキュメント内でのキーバインディングの置き換え

ドキュメント文字列がキーシーケンスを参照する際、それらはカレントである実際のキーバインディングを使用するべきです。これらは、以下で説明する特別なキーシーケンスを使用して行うことができます。通常の方法によるドキュメント文字列へのアクセスは、これらの特別なキーシーケンスをカレントキーバインディングに置き換えます。これは、substitute-command-keysを呼び出すことにより行われます。あなた自身がこの関数を呼び出すこともできます。

以下は、それら特別なシーケンスと、その意味についてのリストです:

\[command]: これは、commandを呼び出すキーシーケンス、またはcommandがキーバインディングをもたない場合は‘M-x command’である。
\{mapvar}: これは、変数mapvarの値であるようなキーマップの要約を意味する。この要約は、describe-bindingsを用いて作成される。
\<mapvar>: これ自体は、何のテキストも意味せず、副作用のためだけに使用される。これは、このドキュメント文字列内にある、後続のすべての‘\[command]’にたいするキーマップとして、mapvarの値を指定する。
`: (grave accent) stands for a left quote. This generates a left single quotation mark, an apostrophe, or a grave accent depending on the value of text-quoting-style. See section Text Quoting Style.
': (apostrophe) stands for a right quote. This generates a right single quotation mark or an apostrophe depending on the value of text-quoting-style.
\=: quotes the following character and is discarded; thus, ‘\=`’ puts ‘`’ into the output, ‘\=\[’ puts ‘\[’ into the output, and ‘\=\=’ puts ‘\=’ into the output.

注意してください: Emacs Lisp内の文字列として記述する際は、‘\’を2つ記述しなければなりません。

User Option: text-quoting-style

The value of this variable is a symbol that specifies the style Emacs should use for single quotes in the wording of help and messages. If the variable’s value is curve, the style is ‘like this’ with curved single quotes. If the value is straight, the style is 'like this' with straight apostrophes. If the value is grave, quotes are not translated and the style is `like this' with grave accent and apostrophe, the standard style before Emacs version 25. The default value nil acts like curve if curved single quotes seem to be displayable, and like grave otherwise.

This option is useful on platforms that have problems with curved quotes. You can customize it freely according to your personal preference.

Function: substitute-command-keys string

この関数は、上述の特別なシーケンスをstringからスキャンして、それらが意味するもので置き換え、その結果を文字列としてリターンする。これにより、そのユーザー自身がカスタマイズした、実際のキーシーケンスを参照するドキュメントが表示できる。

あるコマンドが複数のバインディングをもつ場合、通常この関数は最初に見つかったバインディングを使用する。以下のようにして、コマンドのシンボルプロパティ:advertised-bindingに割り当てることにより、特定のキーバインディングを指定できる:

(put 'undo :advertised-binding [?\C-/])

:advertised-bindingプロパティは、メニューアイテム(メニューバー Barを参照)に表示されるバインディングにも影響する。コマンドが実際にもたないキーバインディングを指定した場合、このプロパティは無視される。

以下は、特別なキーシーケンスの例である:

(substitute-command-keys
   "To abort recursive edit, type `\\[abort-recursive-edit]'.")
⇒ "To abort recursive edit, type ‘C-]’."

(substitute-command-keys
   "ミニバッファーにたいして定義されたキーは:
  \\{minibuffer-local-must-match-map}")
⇒ "ミニバッファーにたいして定義されたキーは:


?               minibuffer-completion-help
SPC             minibuffer-complete-word
TAB             minibuffer-complete
C-j             minibuffer-complete-and-exit
RET             minibuffer-complete-and-exit
C-g             abort-recursive-edit
"

(substitute-command-keys
   "To abort a recursive edit from the minibuffer, type \
`\\<minibuffer-local-must-match-map>\\[abort-recursive-edit]'.")
⇒ "To abort a recursive edit from the minibuffer, type ‘C-g’."

ドキュメント文字列内のテキストにたいしては、他にも特別な慣習があります。たとえば、このマニュアルの関数、変数、およびセクションで参照できます。詳細はドキュメント文字列のヒントを参照してください。

24.4 Text Quoting Style

Typically, grave accents and apostrophes are treated specially in documentation strings and diagnostic messages, and translate to matching single quotation marks (also called “curved quotes”). For example, the documentation string "Alias for `foo'." and the function call (message "Alias for `foo'.") both translate to "Alias for ‘foo’.". Less commonly, Emacs displays grave accents and apostrophes as themselves, or as apostrophes only (e.g., "Alias for 'foo'."). Documentation strings and message formats should be written so that they display well with any of these styles. For example, the documentation string "Alias for 'foo'." is probably not what you want, as it can display as "Alias for ’foo’.", an unusual style in English.

Sometimes you may need to display a grave accent or apostrophe without translation, regardless of text quoting style. In a documentation string, you can do this with escapes. For example, in the documentation string "\\=`(a ,(sin 0)) ==> (a 0.0)" the grave accent is intended to denote Lisp code, so it is escaped and displays as itself regardless of quoting style. In a call to message or error, you can avoid translation by using a format "%s" with an argument that is a call to format. For example, (message "%s" (format "`(a ,(sin %S)) ==> (a %S)" x (sin x))) displays a message that starts with grave accent regardless of text quoting style.

User Option: text-quoting-style

The value of this user option is a symbol that specifies the style Emacs should use for single quotes in the wording of help and messages. If the option’s value is curve, the style is ‘like this’ with curved single quotes. If the value is straight, the style is 'like this' with straight apostrophes. If the value is grave, quotes are not translated and the style is `like this' with grave accent and apostrophe, the standard style before Emacs version 25. The default value nil acts like curve if curved single quotes seem to be displayable, and like grave otherwise.

This option is useful on platforms that have problems with curved quotes. You can customize it freely according to your personal preference.

24.5 ヘルプメッセージの文字記述

以下の関数はイベント、キーシーケンス、文字をテキスト表記(textual descriptions)に変換します。これらの変換された表記は、メッセージ内に任意のテキスト文字やキーシーケンスを含める場合に有用です。なぜなら非プリント文字や空白文字は、プリント文字シーケンスに変換されるからです。空白文字以外のプリント文字は、その文字自身が表記になります。

Function: key-description sequence &optional prefix

この関数は、sequence内の入力イベントにたいして、Emacsの標準表記を含む文字列をリターンする。prefixが非nilの場合、それはsequenceに前置される入力イベントシーケンスであり、リターン値にも含まれる。引数はどちらも文字列、ベクター、またはリストかもしれない。有効なイベントに関する詳細は、入力イベントを参照のこと。

(key-description [?\M-3 delete])
     ⇒ "M-3 <delete>"

(key-description [delete] "\M-3")
     ⇒ "M-3 <delete>"

以下のsingle-key-descriptionの例も参照されたい。

Function: single-key-description event &optional no-angles

この関数は、キーボード入力にたいするEmacsの標準表記として、eventを表記する文字列をリターンする。通常のプリント文字はその文字自身で表れるが、コントロール文字は‘C-’で始まる文字列、メタ文字は‘M-’で始まる文字列、スペース、タブなどは‘SPC’や‘TAB’のように変換される。ファンクションキーのシンボルは、‘<…>’のように角カッコ(angle brackets)の内側に表れる。リストであるようなイベントは、そのリストのCAR内のシンボル名が、角カッコの内側に表れる。

オプション引数no-anglesが非nilの場合、ファンクションキーおよびイベントシンボルを括る角カッコは省略される。これは、角カッコを使用しない古いバージョンのEmacsとの互換性のためである。

(single-key-description ?\C-x)
     ⇒ "C-x"

(key-description "\C-x \M-y \n \t \r \f123")
     ⇒ "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"

(single-key-description 'delete)
     ⇒ "<delete>"

(single-key-description 'C-mouse-1)
     ⇒ "<C-mouse-1>"

(single-key-description 'C-mouse-1 t)
     ⇒ "C-mouse-1"

Function: text-char-description character

この関数は、テキスト内に出現する文字にたいするEmacsの標準表記として、characterを表記する文字列をリターンする。これはsingle-key-descriptionと似ているが、コントロール文字にカレットが前置されて表される点が異なる(これはEmacsバッファー内でコントロール文字を表示する通常の方法である)。他にも、single-key-descriptionが2**27ビットをメタ文字とするのにたいし、text-char-descriptionは2**7ビットをメタ文字とする点が異なる。

(text-char-description ?\C-c)
     ⇒ "^C"

(text-char-description ?\M-m)
     ⇒ "\xed"

(text-char-description ?\C-\M-m)
     ⇒ "\x8d"

(text-char-description (+ 128 ?m))
     ⇒ "M-m"

(text-char-description (+ 128 ?\C-m))
     ⇒ "M-^M"

Command: read-kbd-macro string &optional need-vector: この関数は主にキーボードマクロを操作するために使用されるが、key-descriptionの大雑把な意味で逆の処理にも使用できる。キー表記を含むスペース区切りの文字列でこれを呼び出すと、それに対応するイベントを含む文字列、またはベクターをリターンする。(これは単一の有効なキーシーケンスであるか否かは問わず、何のイベントを使用するかに依存する。キーシーケンスを参照されたい。) need-vectorが非nilの場合、リターン値は常にベクターになる。

24.6 ヘルプ関数

Emacsは、さまざまなビルトインのヘルプ関数を提供し、それらはすべてプレフィックスC-hのサブコマンドとして、ユーザーがアクセスできます。それらについての詳細は、Help in The GNU Emacs Manualを参照してください。ここでは、同様な情報についてプログラムレベルのインターフェイスを説明します。

Command: apropos pattern &optional do-all

This function finds all meaningful symbols whose names contain a match for the apropos pattern pattern. An apropos pattern is either a word to match, a space-separated list of words of which at least two must match, or a regular expression (if any special regular expression characters occur). A symbol is meaningful if it has a definition as a function, variable, or face, or has properties.

関数は、以下のような要素のリストをリターンする:

(symbol score function-doc variable-doc
 plist-doc widget-doc face-doc group-doc)

ここで、scoreはマッチの面からそのシンボルがどれだけ重要に見えるかを比較する整数である。残りの各要素は、symbolにたいする関数、変数、...等のドキュメント文字列(またはnil)である。

これは*Apropos*という名前のバッファーにもシンボルを表示し、その際各行にはドキュメント文字列の先頭から取得した1行説明とともに表示される。

do-allが非nil、またはユーザーオプションapropos-do-allが非nilの場合、aproposは見つかった関数のキーバインディングも表示する。これは重要なものだけでなく、のinternされたすべてのシンボルも表示する(同様にリターン値としてもそれらをリストする)。

Variable: help-map: この変数の値は、HelpキーC-hに続く文字にたいするローカルキーマップである。

Prefix Command: help-command

このシンボルは関数ではなく、関数定義セルにはhelp-mapとして知られる、キーマップを保持する。これは、help.el内で以下のように定義されている:

(define-key global-map (string help-char) 'help-command)
(fset 'help-command help-map)

User Option: help-char

この変数の値は、ヘルプ文字(help character: Helpを意味する文字としてEmacsが認識する文字)である。デフォルトでは、C-hを意味する8が値である。この文字を読み取った際、help-formが非nilのLisp式ならば、Emacsはその式を評価して、結果が文字列の場合はウィンドウ内にそれを表示する。

通常、help-formの値はnilである。その場合、ヘルプ文字はコマンド入力のレベルにおいて特別な意味を有せず、通常の方法におけるキーシーケンスの一部となる。C-hの標準的なキーバインディングは、複数の汎用目的をもつヘルプ機能のプレフィックスキーである。

ヘルプ文字は、プレフィックスキーの後でも特別な意味をもつ。ヘルプ文字がプレフィックスキーのサブコマンドとしてバインディングをもたない場合は、そのプレフィックスキーのすべてのサブコマンドのリストを表示する、describe-prefix-bindingsを実行する。

User Option: help-event-list: The value of this variable is a list of event types that serve as alternative help characters. These events are handled just like the event specified by help-char.

Variable: help-form

この変数が非nilの場合、その値は文字help-charが読み取られるたびに評価されるフォームである。そのフォームの評価により文字列が生成された場合は、その文字列が表示される。

read-event、read-char-choice、read-charを呼び出すコマンドは、それが入力を行う間は、恐らくhelp-formを非nilにバインドすべきであろう(C-hが他の意味をもつ場合は、これを行うべきではない)。この式を評価した結果は、何にたいする入力なのか、そしてそれを正しくエンターする方法を説明する文字列であること。

ミニバッファーへのエントリーにより、この変数はminibuffer-help-formの値にバインドされる(Definition of minibuffer-help-formを参照)。

Variable: prefix-help-command: この変数は、プレフィックスキーにたいするヘルプをプリントする関数を保持する。その関数は、ユーザーが後にヘルプ文字を伴うプレフィックスキーをタイプし、そのヘルプ文字がプレフィックスの後のバインディングをもたないたときに呼び出される。この変数のデフォルト値はdescribe-prefix-bindingsである。

Command: describe-prefix-bindings: この関数は、もっとも最近のプレフィックスキーのサブコマンドすべてにたいするリストを表示する。プレフィックスの説明は、そのキーシーケンスの最後のイベントを除くすべてから構成される(最後のイベントは、恐らくヘルプ文字であろう)。

The following two functions are meant for modes that want to provide help without relinquishing control, such as the electric modes. Their names begin with ‘Helper’ to distinguish them from the ordinary help functions.

Command: Helper-describe-bindings: このコマンドは、ローカルキーマップとグローバルキーマップの両方のキーバインディングすべてのリストを含むヘルプバッファーを表示するウィンドウをポップアップする。これはdescribe-bindingsを呼び出すことにより機能する。

Command: Helper-help

このコマンドは、カレントモードにたいするヘルプを提供する。これはミニバッファー内でメッセージ‘Help (Type ? for further options)’とともにユーザーに入力を求め、その後キーバインディングが何か、何を意図するモードなのかを探すための助けを提供する。これはnilをリターンする。

これは、マップHelper-help-mapを変更することによりカスタマイズできる。

Variable: data-directory: この変数は、Emacsに付随する特定のドキュメントおよびテキストファイルを探すディレクトリーの名前を保持する。

Function: help-buffer: この関数は、ヘルプバッファーの名前(通常は*Help*)をリターンする。そのようなバッファーが存在しない場合は、最初にそれを作成する。

Macro: with-help-window buffer-or-name body…: This macro evaluates body like with-output-to-temp-buffer (see section 一時的な表示), inserting any output produced by its forms into a buffer specified by buffer-or-name, which can be a buffer or the name of a buffer. (Frequently, buffer-or-name is the value returned by the function help-buffer.) This macro puts the specified buffer into Help mode and displays a message telling the user how to quit and scroll the help window. It selects the help window if the current value of the user option help-window-select has been set accordingly. It returns the last value in body.

Function: help-setup-xref item interactive-p: この関数は、*Help*バッファー内のクロスリファレンスデータを更新する。このクロスリファレンスは、ユーザーが‘Back’ボタンまたは‘Forward’ボタン上でクリックした際に、ヘルプ情報の再生成に使用される。*Help*バッファーを使用するほとんどのコマンドは、バッファーをクリアーする前に、この関数を呼び出すべきである。item引数は、(function . args)という形式であること。ここで、functionは引数リストargsで呼び出されるヘルプバッファーを再生成する関数である。コマンド呼び出しがinteractiveに行われた場合、interactive-p引数は非nilである。この場合、*Help*バッファーの‘Back’ボタンにたいするitemのスタックはクリアーされる。

help-buffer、with-help-window、help-setup-xrefの使用例は、describe-symbols exampleを参照してください。

Macro: make-help-screen fname help-line help-text help-map

このマクロは、提供するサブコマンドのリストを表示するプレフィックスキーのように振る舞う、fnameという名前のヘルプコマンドを定義する。

呼び出された際、fnameはウィンドウ内にhelp-textを表示してから、help-mapに応じてキーシーケンスの読み取りと実行を行う。文字列help-textは、help-map内で利用可能なバインディングを説明すべきである。

コマンドfnameは、help-textの表示をスクロールすることによる、自身のいくつかのイベントを処理するために定義される。fnameがこれらのスペシャルイベントのいずれかを読み取った際は、スクロールを行った後で他のイベントを読み取る。自身が処理する以外のイベントを読み取り、そのイベントがhelp-map内にバインディングを有す際は、そのキーのバインディングを実行した後リターンする。

引数help-lineは、help-map内の候補の1行要約であること。Emacsのカレントバージョンでは、オプションthree-step-helpをtにセットした場合のみ、この引数が使用される。

このマクロは、C-h C-hにバインドされるコマンドhelp-for-help内で使用される。

User Option: three-step-help: この変数が非nilの場合、make-help-screenで定義されたコマンドは、最初にエコーエリア内に自身のhelp-line文字列を表示し、ユーザーが再度ヘルプ文字をタイプした場合のみ、長いhelp-text文字列を表示する。

25 ファイル

このチャプターでは検索、作成、閲覧、保存、その他ファイルとディレクトリーにたいして機能する、Emacs Lispの関数および変数について説明します。その他のいくつかのファイルに関する関数についてはバッファー、バックアップとauto-save(自動保存)に関する関数についてはバックアップと自動保存で説明されています。

ファイル関数の多くは、ファイル名であるような引数を1つ以上とります。このファイル名は文字列です。これらの関数のほとんどは、関数expand-file-nameを使用してファイル名引数を展開するので、~は相対ファイル名(../を含む)として正しく処理されます。ファイル名を展開する関数を参照してください。

加えて、特定のmagicファイル名は特別に扱われます。たとえば、リモートファイル名が指定された際、Emacsは適切なプロトコルを通じて、ネットワーク越しにファイルにアクセスします。Remote Files in The GNU Emacs Manualを参照してください。この処理は非常に低いレベルで行われるので、注記されたものを除き、このチャプターで説明するすべての関数が、ファイル名引数としてmagicファイル名を受け入れると想定しても良いでしょう。詳細は、See section 特定のファイル名の“Magic”の作成を参照してください。

ファイルI/O関数がLispエラーをシグナルする際、通常はコンディションfile-errorを使用します(エラーを処理するコードの記述を参照)。ほとんどの場合、オペレーティングシステムからロケールsystem-messages-localeに応じたエラーメッセージが取得され、コーディングシステムlocale-coding-systemを使用してデコードされます(localeを参照)。

25.1 ファイルのvisit		編集のためにEmacsバッファーにファイルを読み込む。
25.2 バッファーの保存		変更されたバッファーをファイルに書き戻す。
25.3 ファイルの読み込み		ファイルをvisitせずにバッファーに読み込む。
25.4 ファイルの書き込み		バッファーの一部から新たなファイルに書き込む。
25.5 ファイルのロック		複数名による同時編集を防ぐためにファイルをlockまたはunlockする。
25.6 ファイルの情報		ファイルの存在、アクセス権、サイズのテスト。
25.7 ファイルの名前と属性の変更		ファイル名のリネームやパーミッションの変更など。
25.8 Files and Secondary Storage		Surviving power and media failures
25.9 ファイルの名前		ファイル名の分解と展開。
25.10 ディレクトリーのコンテンツ		ディレクトリーないのファイルリストの取得。
25.11 ディレクトリーの作成・コピー・削除		ディレクトリーの作成と削除。
25.12 特定のファイル名の“Magic”の作成		特定のファイル名にたいする特別な処理。
25.13 ファイルのフォーマット変換		さまざまなファイルフォーマットへ/からの変換。

25.1 ファイルのvisit

Visiting a file means reading a file into a buffer. Once this is done, we say that the buffer is visiting that file, and call the file the visited file of the buffer.

ファイルとバッファーは、2つの異なる事柄です。ファイルとは、(削除しない限り)コンピューター内に永続的に記録された情報です。一方バッファーとは、編集セッションの終了(またはバッファーのkill)とともに消滅する、Emacs内部の情報です。あるバッファーがファイルをvistしているとき、バッファーぬはファイルからコピーされた情報が含まれます。編集コマンドにより変更されるのは、バッファー内のコピーです。バッファーへの変更によりファイルは変更されません。その変更を永続化させるには、バッファーを保存(save)しなければなりません。これは変更されたバッファーのコンテンツをファイルにコピーして戻すことを意味します。

ファイルとバッファーは異なるにも関わらず、人はバッファーという意味でファイルを呼んだり、その逆を行うことが多々あります。実際のところ、“わたしは間もなく同じ名前のファイルに保存するバッファーを編集している”ではなく、“わたしはファイルを編集している”と言います。人間がこの違いを明示する必要は、通常はありません。しかし、コンピュータープログラムに対処する際は、この違いを心に留めておくのが良いでしょう。

25.1.1 ファイルをvisitする関数

このセクションでは、ファイルのvisitに通常使用される関数を説明します。歴史的な理由により、これらの関数は‘visit-’ではなく、‘find-’で始まる名前をもちます。バッファーをvisitしているファイルの名前へのアクセスや、visitされたファイル名から既存のバッファーを見つける関数および変数については、バッファーのファイル名を参照してください。

Lispプログラム内では、ファイル内容を見たいものの変更したくない場合はテンポラリーバッファー(temporary buffer: 一時的なバッファー)でinsert-file-contentsを使用例するのが、もっとも高速な方法です。時間を要するファイルのvisitは必要ありません。ファイルの読み込みを参照してください。

Command: find-file filename &optional wildcards

このコマンドは、ファイルfilenameをvisitしているバッファーを選択する。visitしている既存のバッファーがあればそのバッファーを使用し、なければバッファーを新たに作成して、そのバッファーにファイルを読み込む。これはそのバッファーをリターンする。

技術的な詳細を別とすると、find-file関数のbodyは基本的には以下と等価である:

(switch-to-buffer (find-file-noselect filename nil nil wildcards))

(ウィンドウ内のバッファーへの切り替えのswitch-to-bufferを参照されたい。)

wildcardsが非nil(これはinteractiveに呼び出された場合は常にtrueである)の場合、find-fileはfilename内のワイルドカード文字を展開して、マッチするすべてのファイルをvisitする。

find-fileがinteractiveに呼び出された際は、ミニバッファー内でfilenameの入力を求める。

Command: find-file-literally filename

このコマンドは、find-fileが行うようにfilenameをvisitするが、フォーマット変換(ファイルのフォーマット変換を参照)、文字コード変換(コーディングシステムを参照)、EOL変換(End of line conversionを参照)を何も行わない。ファイルをvisitしているバッファーはunibyteになり、ファイル名とは無関係にバッファーのメジャーモードはFundamentalモードになる。ファイル内で指定されたファイルローカル変数(ファイルローカル変数を参照)は無視され、自動的な解凍とrequire-final-newlineによるファイル終端への改行追加(require-final-newlineを参照)も無効になる。

Emacsがすでにリテラリー(literally: 文字通り、そのまま)でない方法で同じファイルをvisitしているバッファーをもつ場合、Emacsはその同じファイルをリテラリーにvisitせず、単に既存のバッファーに切り替わることに注意されたい。あるファイルのコンテンツにたいして、確実にリテラリーにアクセスしたい場合は、テンポラリーバッファーを作成し、insert-file-contents-literallyを使用してファイルのコンテンツを読み込むべきである(ファイルの読み込みを参照)。

Function: find-file-noselect filename &optional nowarn rawfile wildcards

この関数は、ファイルをvisitするすべての関数の要である。これは、ファイルfilenameをvisitしているバッファーをリターンする。望むならそのバッファーをカレントにしたり、あるウィンドウ内に表示することができるだろうが、この関数はそれを行わない。

関数は、既存のバッファーがあればそれをリターンし、なければ新たにバッファーを作成し、それにファイルを読み込む。find-file-noselectが既存のバッファーを使用する際は、まずファイルがそのバッファーに最後にvisit、または保存したときから変更されていないことを検証する。ファイルが変更されている場合、この関数は変更されたファイルを再読み込みするかどうかをユーザーに尋ねる。ユーザーが‘yes’と応えた場合、以前に行われたそのバッファー内での編集は失われる。

ファイルの読み込みは、EOL変換、フォーマット変換(ファイルのフォーマット変換を参照)を含む、ファイルコンテンツのデコードを要する(コーディングシステムを参照)。wildcardsが非nilの場合、find-file-noselectはfilename内のワイルドカード文字を展開して、マッチするすべてのファイルをvisitする。

この関数は、オプション引数nowarnがnilの場合は、さまざまな特殊ケースにおいて、警告メッセージ(warning message)、および注意メッセージ(advisory message)を表示する。たとえば、関数がバッファーの作成を必要とし、かつfilenameという名前のファイルが存在しない場合は、エコーエリア内にメッセージ‘(New file)’を表示して、そのバッファーを空のままに留める。

find-file-noselect関数は通常、ファイルを読み込んだ後にafter-find-fileを呼び出す(visitのためのサブルーチンを参照)。この関数はバッファーのメジャーモードのセット、ローカル変数のパース、正にvisitしたファイルより新しいauto-saveファイルが存在する場合のユーザーへの警告を行い、find-file-hook内の関数を実行することにより終了する。

オプション引数rawfileが非nilの場合、after-find-fileは呼び出されず、失敗時にfind-file-not-found-functionsは呼び出されない。さらに、非nil値のrawfileは、コーディングシステム変換およびフォーマット変換を抑制する。

find-file-noselect関数は、通常はファイルfilenameをvisitしているバッファーをリターンする。しかし、ワイルドカードが実際に使用、展開された場合は、それらのファイルをvisitしているバッファーのリストをリターンする。

(find-file-noselect "/etc/fstab")
     ⇒ #<buffer fstab>

Command: find-file-other-window filename &optional wildcards

このコマンドは、ファイルfilenameをvisitしているバッファーを選択するが、選択されたウィンドウではない他のウィンドウでこれを行う。これは、別の既存ウィンドウを使用したり、ウィンドウを分割するかもしれない。ウィンドウ内のバッファーへの切り替えlを参照のこと。

このコマンドがinteractiveに呼び出された際は、filenameの入力を求める。

Command: find-file-read-only filename &optional wildcards

このコマンドは、find-fileのようにファイルfilenameをvisitしているバッファーを選択するが、そのバッファーを読み取り専用(read-only)とマークする。関連する関数および変数については、読み取り専用のバッファーを参照のこと。

このコマンドがinteractiveに呼び出された際は、filenameの入力を求める。

User Option: find-file-wildcards: この変数が非nilの場合、各種find-fileコマンドはワイルドカード文字をチェックして、それらにマッチするすべてのファイルをvisitする(interactiveに呼び出されたとき、またはwildcards引数が非nilのとき)。このオプションがnilの場合、find-fileコマンドはそれらのwildcards引数を無視して、ワイルドカード文字を特別に扱うことは決してない。

User Option: find-file-hook

この変数の値は、ファイルがvisitされた後に呼び出される、関数のリストである。ファイルのローカル変数指定は、(もしあれば)このフックが実行される前に処理されるだろう。フック関数実行時は、そのファイルをvisitしているバッファーがカレントになる。

この変数はノーマルフックである。フックを参照のこと。

Variable: find-file-not-found-functions

この変数の値は、find-fileまたはfind-file-noselectが存在しないファイル名を受け取った際に呼び出される、関数のリストである。存在しないファイルを検知すると、find-file-noselectは直ちにこれらの関数を呼び出す。これらのうち、いずれかが非nilをリターンするまで、リストの順に関数を呼び出す。buffer-file-nameはすでにセットアップ済みである。

関数の値が使用され、多くの場合いくつかの関数だけが呼び出されるので、これはノーマルフックではない。

Variable: find-file-literally: このバッファーローカル変数が非nil値にセットされた場合、save-bufferはあたかもそのバッファーがリテラリー、つまり何の変換も行わずにファイルをvisitしていたかのように振る舞う。コマンドfind-file-literallyは、この変数のローカル値をセットするが、その他の等価な関数およびコマンドも、たとえばファイル終端への改行の自動追加を避けるために、同様にこれを行うことができる。この変数は恒久的にローカルなので、メジャーモードの変更により影響を受けない。

25.1.2 visitのためのサブルーチン

find-file-noselect関数は、2つの重要なサブルーチンcreate-file-bufferおよびafter-find-fileを使用します。これらはユーザーのLispコードでも役に立つことがあります。このセクションでは、それらの使い方について説明します。

Function: create-file-buffer filename

この関数は、filenameのvisitにたいして適切な名前のバッファーを作成して、それをリターンする。これはfilename(ディレクトリー含まず)の名前がフリーならバッファー名にそれを使用し、フリーでなければ未使用の名前を取得するために‘<2>’のような文字列を付加する。バッファーの作成も参照のこと。uniquifyライブラリーは、この関数の結果に影響を与えることに注意されたい。Uniquify in The GNU Emacs Manualを参照のこと。

注意してください: create-file-bufferはファイルに新たなバッファーを関連付けません。バッファーの選択もせず、さらにデフォルトのメジャーモードも使用しません。

(create-file-buffer "foo")
     ⇒ #<buffer foo>

(create-file-buffer "foo")
     ⇒ #<buffer foo<2>>

(create-file-buffer "foo")
     ⇒ #<buffer foo<3>>

この関数は、find-file-noselectにより使用される。この関数自身はgenerate-new-bufferを使用する(バッファーの作成を参照)。

Function: after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes

この関数は、バッファーのメジャーモードをセットして、ローカル変数をパースする(Emacsがメジャーモードを選択する方法を参照)。これはfind-file-noselect、およびデフォルトのリバート関数(リバートを参照)により呼び出される。

ファイルが存在しない理由によりファイルの読み込みがエラーを受け取るが、ディレクトリーは存在する場合、呼び出し側はerrorにたいして非nil値を綿すべきである。この場合、after-find-fileは警告‘(New file)’を発する。より深刻なエラーにたいしては、呼び出し側は通常はafter-find-fileを呼び出すべきでない。

warnが非nilの場合、もしauto-saveファイルが存在し、かつそれがvisitされているファイルより新しいなら、この関数は警告を発する。

noautoが非nilの場合、それはAuto-Saveモードを有効、または無効にしないことを告げる。以前にAuto-Saveモードが有効ならば、有効のまま留まる。

after-find-file-from-revert-bufferが非nilの場合、それはこの関数がrevert-bufferから呼び出されたことを意味する。これに直接的な効果はないが、モード関数およびフック関数の中には、この変数の値をチェックするものがいくつかある。

nomodesが非nilの場合、それはバッファーのメジャーモードを変更せず、ファイル内のローカル変数指定を処理せず、find-file-hookを実行しないことを意味する。この機能は、あるケースにおいてrevert-bufferにより使用される。

after-find-fileが最後に行うのは、リストfind-file-hook内のすべての関数を呼び出すことである。

25.2 バッファーの保存

When you edit a file in Emacs, you are actually working on a buffer that is visiting that file—that is, the contents of the file are copied into the buffer and the copy is what you edit. Changes to the buffer do not change the file until you save the buffer, which means copying the contents of the buffer into the file. Buffers which are not visiting a file can still be “saved”, in a sense, using functions in the buffer-local write-contents-functions hook.

Command: save-buffer &optional backup-option

この関数は、バッファーが最後にvisitされたとき、または保存されたときから変更されている場合は、カレントバッファーのコンテンツを、バッファーによりvisitされているファイルに保存し、変更されていなければ何も行わない。

save-bufferは、バックアップファイルの作成に責任を負う。通常、backup-optionはnilであり、save-bufferはファイルをvisit以降、それが最初の保存の場合のみバックアップファイルを作成する。backup-optionにたいする他の値は、別の条件によるバックアップファイル作成を要求する:

引数4は1つのC-uを、引数64は3つのC-uを示すので、save-bufferはバッファーの次回保存時にこのバージョンのファイルがバックアップされるようマークする。
引数16は2つのC-uを、引数64は3つのC-uを示すので、save-buffer関数はそれを保存する前に、前バージョンのファイルを無条件にバックアップする。
引数0は、無条件にバックアップファイルを何も作成しない。

Command: save-some-buffers &optional save-silently-p pred

このコマンドは、ファイルをvisitしている変更されたバッファーのいくつかを保存する。これは通常、各バッファーごとにユーザーに確認を求める。しかし、save-silently-pが非nilの場合は、ユーザーに質問せずにファイルをvisitしているすべてのバッファーを保存する。

The optional pred argument provides a predicate that controls which buffers to ask about (or to save silently if save-silently-p is non-nil). If pred is nil, that means to use the value of save-some-buffers-default-predicate instead of pred. If the result is nil, it means ask only about file-visiting buffers. If it is t, that means also offer to save certain other non-file buffers—those that have a non-nil buffer-local value of buffer-offer-save (see section バッファーのkill). A user who says ‘yes’ to saving a non-file buffer is asked to specify the file name to use. The save-buffers-kill-emacs function passes the value t for pred.

If the predicate is neither t nor nil, then it should be a function of no arguments. It will be called in each buffer to decide whether to offer to save that buffer. If it returns a non-nil value in a certain buffer, that means do offer to save that buffer.

Command: write-file filename &optional confirm

この関数は、カレントバッファーをファイルfilenameに書き込み、バッファーがそのファイルをvisitしていることにして、未変更とマークする。次にfilenameにもとづいてバッファー名をリネームする。バッファー名を一意にするため、必要なら‘<2>’のような文字列を付加する。処理のほとんどは、set-visited-file-name(バッファーのファイル名を参照)、およびsave-bufferを呼び出すことにより行われる。

confirmが非nilの場合、それは既存のファイルを上書きする前に確認を求めることを意味する。ユーザーがプレフィックス引数を与えない場合、interactiveに確認が求められる。

If filename is a directory name (see section ディレクトリーの名前), write-file uses the name of the visited file, in directory filename. If the buffer is not visiting a file, it uses the buffer name instead.

Saving a buffer runs several hooks. It also performs format conversion (see section ファイルのフォーマット変換). Note that these hooks, described below, are only run by save-buffer, they are not run by other primitives and functions that write buffer text to files, and in particular auto-saving (see section 自動保存) doesn’t run these hooks.

Variable: write-file-functions

この変数の値は、バッファーをvisitされているファイルに書き出す前に呼び出される、関数のリストである。それらのうちのいずれかが非nilをリターンした場合、そのファイルは書き込み済みだと判断され、残りの関数は呼び出されないし、ファイルを書き込むための通常のコードも実行されない。

write-file-functions内の関数が非nilをリターンした場合、(それが適切であれば)その関数はファイルをバックアップする責任を負う。これを行うには、以下のコードを実行する:

(or buffer-backed-up (backup-buffer))

You might wish to save the file modes value returned by backup-buffer and use that (if non-nil) to set the mode bits of the file that you write. This is what save-buffer normally does. See section Making Backup Files.

write-file-functions内のフック関数は、データのエンコード(が望ましければ)にも責任を負う。これらは適切なコーディングシステムと改行規則(Lispでのコーディングシステムを参照)を選択してエンコード(明示的なエンコードとデコードを参照)を処理し、使用されていたコーディングシステム(エンコーディングとI/Oを参照)をlast-coding-system-usedにセットしなければならない。

バッファー内でこのフックをローカルにセットした場合、バッファーはそのファイル、またはバッファーのコンテンツを取得したファイルに類するものに関連付けられる。このようにして、変数は恒久的にローカルであるとマークされるので、メジャーモードの変更がバッファーローカルな値を変更することはない。その一方で、set-visited-file-nameを呼び出すことにより、変数はリセットされるだろう。これを望まない場合は、かわりにwrite-contents-functionsを使用したいと思うだろう。

たとえこれがノーマルフックでないとしても、このリストを操作するためにadd-hookおよびremove-hookを使用することはできる。フックを参照のこと。

Variable: write-contents-functions

This works just like write-file-functions, but it is intended for hooks that pertain to the buffer’s contents, not to the particular visited file or its location, and can be used to create arbitrary save processes for buffers that aren’t visiting files at all. Such hooks are usually set up by major modes, as buffer-local bindings for this variable. This variable automatically becomes buffer-local whenever it is set; switching to a new major mode always resets this variable, but calling set-visited-file-name does not.

このフック内の関数のいずれかが非nilをリターンした場合、そのファイルはすでに書き込み済みとみなされ、残りの関数は呼び出されず、write-file-functions内の関数も呼び出されない。

When using this hook to save buffers that are not visiting files (for instance, special-mode buffers), keep in mind that, if the function fails to save correctly and returns a nil value, save-buffer will go on to prompt the user for a file to save the buffer in. If this is undesirable, consider having the function fail by raising an error.

User Option: before-save-hook: このノーマルフックは、visitしているファイルにバッファーが保存される前に実行される。保存が通常の方法で行われるか、あるいは上述のフックのいずれかで行われたかは問題にしない。たとえば、copyright.elプログラムは、ファイルの保存において、それの著作権表示が今年であることを確認するために、このフックを使用する。

User Option: after-save-hook: このノーマルフックは、visitしているファイルにバッファーを保存した後に実行される。このフックの使用例の1つは、Fast Lockモードにある。このモードは、キャッシュファイルにハイライト情報を保存するために、このフックを使用している。

User Option: file-precious-flag

この変数が非nilの場合、save-bufferは保存ファイルがもつ名前のかわりに、一時的な名前で新たなファイルに書き込み、エラーがないと明確になった後にファイルを意図する名前にリネームすることにより、保存中のI/Oエラーから防御する。この手順は、無効なファイルが原因となるディスク容量逼迫のような問題を防ぐ。

副作用として、バックアップ作成にコピーが必要になる。リネームかコピーのどちらでバックアップするか?を参照のこと。しかし同時に、この高価なファイル保存により、保存したファイルと他のファイル名との間のすべてのハードリンクは切断される。

いくつかのモードは、特定のバッファーにおいて、この変数に非nilのバッファーローカル値を与える。

User Option: require-final-newline

この変数は、ファイルが改行で終わらないように書き込まれるかどうかを決定する。変数の値がtの場合、save-bufferはバッファーの終端に改行がなければ暗黙理に改行を追加する。値がvisitの場合、Emacsはファイルをvisitした直後に不足している改行を追加する。値がvisit-saveの場合、Emacsはvisitと保存の両方のタイミングで、不足している改行を追加する。その他の非nil値にたいしては、そのようなケースが生じるたびに、改行を追加するかどうか、save-bufferがユーザーに尋ねる。

変数の値がnilの場合、save-bufferは改行を追加しない。デフォルト値はnilだが、特定のバッファーでこれをtにセットするメジャーモードも少数存在する。

バッファーのファイル名の関数set-visited-file-nameも参照されたい。

25.3 ファイルの読み込み

ファイルのコンテンツをバッファーにコピーするためには、関数insert-file-contentsを使用しします(マークをセットするので、Lispプログラム内でコマンドinsert-fileは使用してはならない)。

Function: insert-file-contents filename &optional visit beg end replace

この関数は、ファイルfilenameのコンテンツを、カレントバッファーのポイントの後に挿入する。これは絶対ファイル名と、挿入だれたデータの長さからなるリストをリターンする。filenameが読み取り可能なファイルの名前でない場合は、エラーがシグナルされる。

この関数は、定義されたファイルフォーマットに照らしてファイルのコンテンツをチェックして、適切ならそのコンテンツの変換、およびリストafter-insert-file-functions内の関数の呼び出しも行う。ファイルのフォーマット変換を参照のこと。通常は、リストafter-insert-file-functions内のいずれかの関数が、EOL変換を含むファイルコンテンツのデコードに使用される、コーディングシステム(コーディングシステムを参照)を判断する。しかし、ファイルにnullバイトが含まれる場合、デフォルトではコード変換なしでvisitされる。inhibit-null-byte-detectionを参照のこと。

visitが非nilの場合、この関数は追加でそのバッファーを未変更とマークして、そのバッファーのさまざまなフィールドをセットアップして、バッファーがファイルfilenameをvisitしているようにする。これらのフィールドにはバッファーがvisitしたファイルの名前、最終保存したファイルのmodtimeが含まれる。これらの機能はfind-file-noselectにより使用され、恐らくあなた自身が使用するべきではない。

begおよびendが非nilの場合、それらはファイル挿入範囲を指定する、バイトオフセット数値であること。この場合、visitはnilでなければならない。たとえば、

(insert-file-contents filename nil 0 500)

これはファイルの先頭500文字(バイト)を挿入する。

引数replaceが非nilの場合、それはバッファーのコンテンツ(実際にはアクセス可能な範囲)を、ファイルのコンテンツで置き換えることを意味する。これは単にバッファーのコンテンツを削除してファイル全体を挿入するより優る。なぜなら、(1)マーカー位置を維持し、(2)undoリストに配すデータも少ないからである。

replaceとvisitがnilであれば、insert-file-contentsで(FIFOやI/Oデバイスのような)スペシャルファイルの読み取りが可能である。

Function: insert-file-contents-literally filename &optional visit beg end replace: This function works like insert-file-contents except that it does not run after-insert-file-functions, and does not do format decoding, character code conversion, automatic uncompression, and so on.

他のプログラムがファイルを読めるように、他のプロセスにファイル名を渡したい場合は、関数file-local-copyを使用します。特定のファイル名の“Magic”の作成を参照してください。

25.4 ファイルの書き込み

関数append-to-fileおよびwrite-regionを使用することにより、ディスク上のファイルに直接、バッファーのコンテンツ、またはバッファーの一部を書き込むことができます。visitされているファイルに書き込むために、これらの関数を使用しないでください。これにより、visitにたいするメカニズムが混乱するかもしれません。

Command: append-to-file start end filename

この関数は、カレントバッファー内で、startとendによるリージョンのコンテンツを、ファイルfilenameの終端に追加する。そのファイルが存在しない場合は作成する。この関数はnilをリターンする。

filenameに書込不可能なファイル、またはファイルを作成不可なディレクトリー内の存在しないファイルを指定した場合は、エラーがシグナルされる。

Lispから呼び出した場合、この関数は以下と完全に等価である:

(write-region start end filename t)

Command: write-region start end filename &optional append visit lockname mustbenew

この関数は、カレントバッファー内のstartとendで区切られたリージョンを、filenameで指定されたファイルに書き込む。

startがnilの場合、このコマンドはバッファーのコンテンツ全体(アクセス可能な範囲だけではない)をファイルに書き込み、endは無視する。

startが文字列の場合、write-regionはバッファーのテキストではなく、その文字列を追加する。その場合、endは無視される。

appendが非nilの場合は、指定されたテキストが(もしあれば)既存のファイルコンテンツに追加される。appendが数字の場合、write-regionはファイル開始位置からそのバイトオフセットをseekして、データをそこに書き込む。

If mustbenew is non-nil, then write-region asks for confirmation if filename names an existing file. If mustbenew is the symbol excl, then write-region does not ask for confirmation, but instead it signals an error file-already-exists if the file already exists. Although write-region normally follows a symbolic link and creates the pointed-to file if the symbolic link is dangling, it does not follow symbolic links if mustbenew is excl.

mustbenewがexclのときは、存在するファイルのテストに特別なシステム機能を使用する。少なくともローカルディスク上のファイルにたいしては、Emacsがファイルを作成する前に、Emacsに通知せずに他のプログラムが同じ名前のファイルを作成することはありえない。

visitがtの場合、Emacsはバッファーとファイルの関連付けを設定し、そのバッファーがそのファイルをvictimする。また、カレントバッファーにたいする最終ファイル変更日時にfilenameをセットして、そのバッファーを未変更としてマークする。この機能はsave-bufferにより使用されるが、おそらくあなた自身が使用するべきではないだろう。

visitが文字列の場合、それはvisitするファイルの名前を指定する。この方法を使えば、そのバッファーが別のファイルをvisitしていると記録しつつ、１つのファイル(filename)にデータを書き込むことができる。引数visitは、エコーエリアに使用される他に、ファイルのロックにも使用され、visitがbuffer-file-nameに格納される。この機能は、file-precious-flagの実装に使用される。自分が何をしているか本当にわかっているのでなければ、これを使用してはならない。

オプション引数locknameが非nilの場合、それはロックとアンロックの目的に使用する、filenameおよびvisitをオーバーライドするファイル名を指定する。

関数write-regionは、書き込むデータをbuffer-file-formatにより指定される、適切なファイルフォーマットに変換しするとともに、リストwrite-region-annotate-functions内の関数の呼び出しも行う。ファイルのフォーマット変換を参照のこと。

Normally, write-region displays the message ‘Wrote filename’ in the echo area. This message is inhibited if visit is neither t nor nil nor a string, or if Emacs is operating in batch mode (see section batchモード). This feature is useful for programs that use files for internal purposes, files that the user does not need to know about.

Variable: write-region-inhibit-fsync: If this variable’s value is nil, write-region uses the fsync system call after writing a file. Although this slows Emacs down, it lessens the risk of data loss after power failure. If the value is t, Emacs does not use fsync. The default value is nil when Emacs is interactive, and t when Emacs runs in batch mode. See section Files and Secondary Storage.

Macro: with-temp-file file body…

with-temp-fileマクロは、一時バッファー(temporary buffer)をカレントバッファーとしてbodyフォームを評価して、最後にそのバッファーのコンテンツをfileに書き込む。これは終了時に一時バッファーをkillして、with-temp-fileフォームの前にカレントだったバッファーをリストアする。その後、body内の最後のフォームの値をリターンする。

throwやエラーによる異常なexit(abnormal exit)でも、カレントバッファーはリストアされる(非ローカル脱出を参照)。

The Current Bufferのwith-temp-bufferも参照のこと。

25.5 ファイルのロック

2人のユーザーが同時に同じファイルを編集する際、おそらく彼らは互いに干渉しあうでしょう。Emacsは、ファイルが変更される際にファイルロック(file lock)を記録することにより、このような状況の発生を防ぎます。そして、Emacsは他のEmacsジョブにロックされているファイルをvisitしているバッファーへの変更の最初の試みを検知して、ユーザーに何を行うか尋ねます。このファイルロックの実態は、編集中のファイルと同じディレクトリーに格納される、特別な名前をもつシンボリックリンクです(シンボリックリンクをサポートしないファイルシステムでは、通常のファイルが使用される)。

When you access files using NFS, there may be a small probability that you and another user will both lock the same file simultaneously. If this happens, it is possible for the two users to make changes simultaneously, but Emacs will still warn the user who saves second. Also, the detection of modification of a buffer visiting a file changed on disk catches some cases of simultaneous editing; see バッファーの変更 Time.

Function: file-locked-p filename

この関数は、ファイルfilenameがロックされていなければnilをリターンする。このEmacsプロセスによりロックされている場合はtをリターンし、他のEmacsジョブによりロックされている場合はロックしたユーザーの名前をリターンする。

(file-locked-p "foo")
     ⇒ nil

Function: lock-buffer &optional filename: This function locks the file filename, if the current buffer is modified. The argument filename defaults to the current buffer’s visited file. Nothing is done if the current buffer is not visiting a file, or is not modified, or if the option create-lockfiles is nil.

Function: unlock-buffer: This function unlocks the file being visited in the current buffer, if the buffer is modified. If the buffer is not modified, then the file should not be locked, so this function does nothing. It also does nothing if the current buffer is not visiting a file, or is not locked.

User Option: create-lockfiles: この変数がnilの場合、Emacsはファイルをロックしない。

Function: ask-user-about-lock file other-user

この関数は、ユーザーがfileの変更を試みたが、それが名前other-userのユーザーにロックされていたとき呼び出される。この関数のデフォルト定義は、何を行うかユーザーに尋ねる関数である。この関数がリターンする値は、Emacsが次に何を行うかを決定する:

値tは、そのファイルのロックを奪うことを意味する。その場合、other-userはロックを失い、このユーザーがファイルを編集することができる。
値nilは、ロックを無視して、とにかくユーザーがファイルを編集できるようにすることを意味する。
この関数は、かわりにエラーfile-lockedをシグナルする。この場合、ユーザーが行おうとしていた変更は行われない。
このエラーにたいするエラーメッセージは、以下のようになる:
```
error→ File is locked: file other-user
```
ここで、fileはファイル名、other-userはそのファイルのロックを所有するユーザーの名前である。

望むなら、他の方法で判定を行う独自のバージョンで、ask-user-about-lock関数を置き換えることができる。

25.6 ファイルの情報

このセクションでは、ファイル(またはディレクトリーやシンボリックリンク)に関して、ファイルが読み込み可能か、書き込み可能か、あるいはファイルのサイズなｍのような、さまざまなタイプの情報を取得する関数を説明します。これらの関数はすべて、引数にファイルの名前を取ります。注記した場合を除き、これらの引数には既存のファイルを指定する必要があり、ファイルが存在しない場合はエラーをシグナルします。

スペースで終わるファイル名には気をつけてください。いくつかのファイルシステム(特にMS-Windows)では、ファイル名の末尾の空白文字は、暗黙かつ自動的に無視されます。

25.6.1 アクセシビリティのテスト		そのファイルは読み取り可能か？書き込み可能か？
25.6.2 ファイル種別の区別		それはディレクトリー？それともシンボリックリンク？
25.6.3 本当の名前		シンボリックリンクが行き着くファイル名。
25.6.4 ファイルの属性		ファイルのサイズ？更新日時など。
25.6.5 拡張されたファイル属性		アクセス制御にたいするファイル属性の拡張。
25.6.6 標準的な場所へのファイルの配置		標準的な場所でファイルを見つける方法。

25.6.1 アクセシビリティのテスト

These functions test for permission to access a file for reading, writing, or execution. Unless explicitly stated otherwise, they follow symbolic links. See section ファイル種別の区別.

いくつかのオペレーティングシステムでは、ACL(Access Control Lists: アクセス制御リスト)のような機構を通じて、より複雑なアクセスパーミッションセットが指定できます。それらのパーミッションにたいする問い合わせやセットの方法については、拡張されたファイル属性を参照してください。

Function: file-exists-p filename

This function returns t if a file named filename appears to exist. This does not mean you can necessarily read the file, only that you can find out its attributes. (On GNU and other POSIX-like systems, this is true if the file exists and you have execute permission on the containing directories, regardless of the permissions of the file itself.)

ファイルが存在しない、またはACLポリシーがファイル属性を調べることを禁止する場合、この関数はnilをリターンする。

Directories are files, so file-exists-p can return t when given a directory. However, because file-exists-p follows symbolic links, it returns t for a symbolic link name only if the target file exists.

Function: file-readable-p filename: この関数は、filenameという名前のファイルが存在し、それを読み取ることが可能な場合はtをリターンする。それ以外はnilをリターンする。

Function: file-executable-p filename: This function returns t if a file named filename exists and you can execute it. It returns nil otherwise. On GNU and other POSIX-like systems, if the file is a directory, execute permission means you can check the existence and attributes of files inside the directory, and open those files if their modes permit.

Function: file-writable-p filename

この関数は、filenameという名前のファイルに書き込み可能、または作成可能可能な場合はtをリターンする。それ以外はnilをリターンする。ファイルが存在し、それに書き込むことができるなら、ファイルは書き込み可能である。ファイルが存在せず、指定されたディレクトリーが存在して、そのディレクトリーに書き込むことができるなら、書き込み可能である。

以下の例では、fooは親ディレクトリーが存在しないので、たとえユーザーがそのディレクトリーを作成可能であっても、ファイルは書き込み可能ではない。

(file-writable-p "~/no-such-dir/foo")
     ⇒ nil

Function: file-accessible-directory-p dirname

この関数は、ファイルとしての名前がdirnameであるようなディレクトリー内にある既存のファイルをオープンするパーミッションをもつ場合は、tをリターンする。それ以外(またはそのようなディレクトリーが存在しない場合)はnilをリターンする。dirnameの値はディレクトリー名(/foo/など)、または名前がディレクトリー(最後のスラッシュがない/fooなど)であるようなファイルである。

たとえば、以下では/foo/内の任意のファイルを読み取る試みは、エラーになると推測される:

(file-accessible-directory-p "/foo")
     ⇒ nil

Function: access-file filename string: この関数は、読み取り用にファイルfilenameをオープンして、クローズした後にnilをリターンする。しかし、オープンに失敗した場合は、stringをエラーメッセージのテキストに使用して、エラーをシグナルする。

Function: file-ownership-preserved-p filename &optional group

この関数は、ファイルfilenameを削除して、それを新たに作成しても、そのファイルの所有者が変更されずに維持される場合は、tをリターンする。これは、存在しないファイルにたいしてもtをリターンする。

オプション引数groupが非nilの場合、この関数はファイルのグループが変更されないこともチェックする。

This function does not follow symbolic links.

Function: file-modes filename

This function returns the mode bits of filename—an integer summarizing its read, write, and execution permissions. This function follows symbolic links. If the file does not exist, the return value is nil.

モードビットの説明は、See File permissions in The GNU Coreutils Manualを参照のこと。たとえば最下位ビットが1なら、そのファイルは実行可能、2ビット目が1なら書き込み可能、...となる。設定できる最大の値は4095(8進の7777)であり、これはすべてのユーザーが読み取り、書き込み、実行のパーミッションをもち、他のユーザーとグループにたいしてSUIDビット、およびstickyビットがセットされる。

これらのパーミッションのセットに使用されるset-file-modes関数については、ファイルの名前と属性の変更を参照のこと。

(file-modes "~/junk/diffs")
     ⇒ 492               ; 10進整数

(format "%o" 492)
     ⇒ "754"             ; 8進に変換した値

(set-file-modes "~/junk/diffs" #o666)
     ⇒ nil

$ ls -l diffs
-rw-rw-rw- 1 lewis lewis 3063 Oct 30 16:00 diffs

MS-DOS note: On MS-DOS, there is no such thing as an executable file mode bit. So file-modes considers a file executable if its name ends in one of the standard executable extensions, such as .com, .bat, .exe, and some others. Files that begin with the POSIX-standard ‘#!’ signature, such as shell and Perl scripts, are also considered executable. Directories are also reported as executable, for compatibility with POSIX. These conventions are also followed by file-attributes (see section ファイルの属性).

25.6.2 ファイル種別の区別

このセクションでは、ディレクトリー、シンボリックリンク、および通常ファイルのような、さまざまな種類のファイルを区別する方法を説明します。

Symbolic links are ordinarily followed wherever they appear. For example, to interpret the file name a/b/c, any of a, a/b, and a/b/c can be symbolic links that are followed, possibly recursively if the link targets are themselves symbolic links. However, a few functions do not follow symbolic links at the end of a file name (a/b/c in this example). Such a function is said to not follow symbolic links.

Function: file-symlink-p filename

If the file filename is a symbolic link, this function does not follow it and instead returns its link target as a string. (The link target string is not necessarily the full absolute file name of the target; determining the full file name that the link points to is nontrivial, see below.)

ファイルfilenameがシンボリックリンクではない、または存在しない場合、file-symlink-pはnilをリターンする。

この関数の使用例をいくつか示す:

(file-symlink-p "not-a-symlink")
     ⇒ nil

(file-symlink-p "sym-link")
     ⇒ "not-a-symlink"

(file-symlink-p "sym-link2")
     ⇒ "sym-link"

(file-symlink-p "/bin")
     ⇒ "/pub/bin"

Note that in the third example, the function returned sym-link, but did not proceed to resolve it, although that file is itself a symbolic link. That is because this function does not follow symbolic links—the process of following the symbolic links does not apply to the last component of the file name.

この関数がリターンするのは、そのシンボリックリンクに何が記録されているかを示す文字列であり、それにはディレクトリー部分が含まれていても、いなくても構わない。この関数は完全修飾されたファイル名を生成するためにリンクターゲットを展開しないし、リンクターゲットが絶対ファイル名でなければ、(もしあっても)filename引数のディレクトリー部分は使用しない。以下に例を示す:

(file-symlink-p "/foo/bar/baz")
     ⇒ "some-file"

ここでは、たとえ与えられた/foo/bar/bazが完全修飾されたファイル名であるにも関わらず、その結果は異なり、実際には何のディレクトリー部分ももたない。some-file自体がシンボリックリンクかもしれないので、単にその前に先行ディレクトリーを追加することはできず、絶対ファイル名を生成するために、単にexpand-file-name(ファイル名を展開する関数を参照)を使用することもできないからである。

この理由により、あるファイルがシンボリックリンクか否かという単一の事実よりも多くを判定する必要がある場合に、この関数が有用であることは稀である。実際にリンクターゲットのファイル名が必要な場合は、本当の名前で説明するfile-chase-linksまたはfile-truenameを使用すること。

Function: file-directory-p filename

This function returns t if filename is the name of an existing directory, nil otherwise. This function follows symbolic links.

(file-directory-p "~rms")
     ⇒ t

(file-directory-p "~rms/lewis/files.texi")
     ⇒ nil

(file-directory-p "~rms/lewis/no-such-file")
     ⇒ nil

(file-directory-p "$HOME")
     ⇒ nil

(file-directory-p
 (substitute-in-file-name "$HOME"))
     ⇒ t

Function: file-regular-p filename: This function returns t if the file filename exists and is a regular file (not a directory, named pipe, terminal, or other I/O device). This function follows symbolic links.

25.6.3 本当の名前

ファイルの実名(truename)とは、全階層においてシンボリックリンクを残らずフォローした後、名前コンポーネントに出現する‘.’と‘..’を除いて簡略化した名前のことです。これは、そのファイルにたいする正規名(canonical name)の一種です。ファイルが常に一意な実名をもつ訳ではありません。あるファイルにたいする異なる実名の個数は、そのファイルにたいするハードリンクの個数と同じです。しかし、実名はシンボリックリンクによる名前の変動を解消するのに有用です。

Function: file-truename filename

この関数は、ファイルfilenameの実名をリターンする。引数が絶対ファイル名でない場合、この関数は最初にdefault-directoryにたいしてこれを展開する。

この関数は、環境変数を展開しない。これを行うのはsubstitute-in-file-nameだけである。Definition of substitute-in-file-nameを参照のこと。

If you may need to follow symbolic links preceding ‘..’ appearing as a name component, call file-truename without prior direct or indirect calls to expand-file-name. Otherwise, the file name component immediately preceding ‘..’ will be simplified away before file-truename is called. To eliminate the need for a call to expand-file-name, file-truename handles ‘~’ in the same way that expand-file-name does.

If the target of a symbolic links has remote file name syntax, file-truename returns it quoted. See section Functions that Expand Filenames.

Function: file-chase-links filename &optional limit

この関数は、filenameで始まるシンボリックリンクを、シンボリックリンクではない名前のファイル名までフォローして、そのファイル名をリターンする。この関数は、親ディレクトリーの階層にあるシンボリックリンクをフォローしない。

limitに数を指定した場合は、その数のリンクを追跡した後、この関数はたとえそれが依然としてシンボリックリンクであっても、それをリターンする。

file-chase-linksとfile-truenameの違いを説明するために、/usr/fooがディレクトリー/home/fooへのシンボリックリンクであり、/home/foo/helloが(少なくともシンボリックリンクではない)通常ファイル、または存在しないファイルであるとします。この場合は以下のようになります:

(file-chase-links "/usr/foo/hello")
     ;; 親ディレクトリーのリンクはフォローしない
     ⇒ "/usr/foo/hello"
(file-truename "/usr/foo/hello")
     ;; /homeはシンボリックリンクではないと仮定
     ⇒ "/home/foo/hello"

Function: file-equal-p file1 file2: この関数は、ファイルfile1とfile2の名前が同じファイルの場合はtをリターンする。これは、リモートファイル名も適切な方法で処理することを除き、実名の比較と似ている。file1またはfile2が存在しない場合、リターン値は不定である。

Function: file-name-case-insensitive-p filename

Sometimes file names or their parts need to be compared as strings, in which case it’s important to know whether the underlying filesystem is case-insensitive. This function returns t if file filename is on a case-insensitive filesystem. It always returns t on MS-DOS and MS-Windows. On Cygwin and macOS, filesystems may or may not be case-insensitive, and the function tries to determine case-sensitivity by a runtime test. If the test is inconclusive, the function returns t on Cygwin and nil on macOS.

Currently this function always returns nil on platforms other than MS-DOS, MS-Windows, Cygwin, and macOS. It does not detect case-insensitivity of mounted filesystems, such as Samba shares or NFS-mounted Windows volumes. On remote hosts, it assumes t for the ‘smb’ method. For all other connection methods, runtime tests are performed.

Function: file-in-directory-p file dir: この関数は、fileがディレクトリーdir内のファイル、またはサブディレクトリーの場合は、tをリターンする。また、fileとdirが同じディレクトリーの場合も、tをリターンする。この関数は、2つのディレクトリーの実名を比較する。dirが既存のディレクトリーの名前でない場合、リターン値はnilである。

Function: vc-responsible-backend file

This function determines the responsible VC backend of the given file. For example, if emacs.c is a file tracked by Git, (vc-responsible-backend "emacs.c") returns ‘Git’. Note that if file is a symbolic link, vc-responsible-backend will not resolve it—the backend of the symbolic link file itself is reported. To get the backend VC of the file to which file refers, wrap file with a symbolic link resolving function such as file-chase-links:

(vc-responsible-backend (file-chase-links "emacs.c"))

25.6.4 ファイルの属性

このセクションでは、ファイルの詳細な情報を取得する関数について説明します。それらの情報にはファイルの所有者やグループの番号、ファイル名の個数、inode番号、サイズやアクセス日時、変更日時が含まれます。

Function: file-newer-than-file-p filename1 filename2

この関数は、ファイルfilename1がファイルfilename2より新しい場合は、tをリターンする。filename1が存在しない場合はnil、filename1は存在するがfilename2が存在しない場合はtをリターンする。

以下の例では、aug-19が19日、aug-20が20日に書き込まれ、ファイルno-fileは存在しないものとする。

(file-newer-than-file-p "aug-19" "aug-20")
     ⇒ nil

(file-newer-than-file-p "aug-20" "aug-19")
     ⇒ t

(file-newer-than-file-p "aug-19" "no-file")
     ⇒ t

(file-newer-than-file-p "no-file" "aug-19")
     ⇒ nil

Function: file-attributes filename &optional id-format

This function returns a list of attributes of file filename. If the specified file’s attributes cannot be accessed, it returns nil. This function does not follow symbolic links. The optional parameter id-format specifies the preferred format of attributes UID and GID (see below)—the valid values are 'string and 'integer. The latter is the default, but we plan to change that, so you should specify a non-nil value for id-format if you use the returned UID or GID.

On GNU platforms when operating on a local file, this function is atomic: if the filesystem is simultaneously being changed by some other process, this function returns the file’s attributes either before or after the change. Otherwise this function is not atomic, and might return nil if it detects the race condition, or might return a hodgepodge of the previous and current file attributes.

Accessor functions are provided to access the elements in this list. The accessors are mentioned along with the descriptions of the elements below.

リストの要素は順に:

t for a directory, a string for a symbolic link (the name linked to), or nil for a text file (file-attribute-type).
The number of names the file has (file-attribute-link-number). Alternate names, also known as hard links, can be created by using the add-name-to-file function (see section ファイルの名前と属性の変更).
The file’s UID, normally as a string (file-attribute-user-id). However, if it does not correspond to a named user, the value is a number.
The file’s GID, likewise (file-attribute-group-id).
The time of last access, as a list of four integers (sec-high sec-low microsec picosec) (file-attribute-access-time). (This is similar to the value of current-time; see 時刻.) The value is truncated to that of the filesystem’s timestamp resolution; for example, on some FAT-based filesystems, only the date of last access is recorded, so this time will always hold the midnight of the day of the last access.
The time of last modification as a list of four integers (as above) (file-attribute-modification-time). This is the last time when the file’s contents were modified.
The time of last status change as a list of four integers (as above) (file-attribute-status-change-time). This is the time of the last change to the file’s access mode bits, its owner and group, and other information recorded in the filesystem for the file, beyond the file’s contents.
The size of the file in bytes (file-attribute-size). This is floating point if the size is too large to fit in a Lisp integer.
The file’s modes, as a string of ten letters or dashes, as in ‘ls -l’ (file-attribute-modes).
後方互換のために提供される不定値。
The file’s inode number (file-attribute-inode-number). If possible, this is an integer. If the inode number is too large to be represented as an integer in Emacs Lisp but dividing it by 2^{16} yields a representable integer, then the value has the form (high . low), where low holds the low 16 bits. If the inode number is too wide for even that, the value is of the form (high middle . low), where high holds the high bits, middle the middle 24 bits, and low the low 16 bits.
The filesystem number of the device that the file is on file-attribute-device-number). Depending on the magnitude of the value, this can be either an integer or a cons cell, in the same manner as the inode number. This element and the file’s inode number together give enough information to distinguish any two files on the system—no two files can have the same values for both of these numbers.

たとえば、以下はfiles.texiのファイル属性である:

(file-attributes "files.texi" 'string)
     ⇒  (nil 1 "lh" "users"
          (20614 64019 50040 152000)
          (20000 23 0 0)
          (20614 64555 902289 872000)
          122295 "-rw-rw-rw-"
          t (5888 2 . 43978)
          (15479 . 46724))

この結果を解釈すると:

nil: ディレクトリーでもシンボリックリンクでもない。
1: (カレントデフォルトディレクトリー内で名前files.texiは)単一の名前をもつ。
"lh": is owned by the user with name ‘lh’.
"users": is in the group with name ‘users’.
(20614 64019 50040 152000): 最終アクセスがOctober 23, 2012, at 20:12:03.050040152 UTC。
(20000 23 0 0): 最終更新がJuly 15, 2001, at 08:53:43 UTC。
(20614 64555 902289 872000): 最終ステータス変更がOctober 23, 2012, at 20:20:59.902289872 UTC。
122295: バイト長は122295バイト(しかしマルチバイトシーケンスが含まれていたり、EOLフォーマットがCRLFの場合は122295文字が含まれないだろう)。
"-rw-rw-rw-": 所有者、グループ、その他にたいして読み取り、書き込みアクセスのモードをもつ。
t: 単なるプレースホルダーであり、何の情報ももたない。
(5888 2 . 43978): inode番号は6473924464520138。
(15479 . 46724): ファイルシステムのデバイス番号は1014478468。

Function: file-nlinks filename

This function returns the number of names (i.e., hard links) that file filename has. If the file does not exist, this function returns nil. Note that symbolic links have no effect on this function, because they are not considered to be names of the files they link to. This function does not follow symbolic links.

$ ls -l foo*
-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo
-rw-rw-rw- 2 rms rms 4 Aug 19 01:27 foo1

(file-nlinks "foo")
     ⇒ 2

(file-nlinks "doesnt-exist")
     ⇒ nil

25.6.5 拡張されたファイル属性

On some operating systems, each file can be associated with arbitrary extended file attributes. At present, Emacs supports querying and setting two specific sets of extended file attributes: Access Control Lists (ACLs) and SELinux contexts. These extended file attributes are used, on some systems, to impose more sophisticated file access controls than the basic Unix-style permissions discussed in the previous sections.

ACLとSELinuxについての詳細な解説は、このマニュアルの範囲を超えます。わたしたちの目的のためには、それぞれのファイルはACL(ACLベースのファイル制御システムの元でACLのプロパティを指定)および/またはSELinuxコンテキスト(SELinuxシステムの元でSELinuxのプロパティを指定)に割り当てることができる、という理解でよいでしょう。

Function: file-acl filename

この関数は、ファイルfilenameにたいするACLをリターンする。ACLにたいする正確なLisp表現は不確定(かつ将来のEmacsバージョンで変更され得る)だが、これはset-file-aclが引数aclにとる値と同じである(ファイルの名前と属性の変更を参照)。

根底にあるACL実装はプラットフォーム固有である。EmacsはGNU/LinuxおよびBSDではPOSIX ACLインターフェイスを使用し、MS-WindowsではネイティブのファイルセキュリティAPIをPOSIX ACLインターフェイスでエミュレートする。

ACLサポートなしでEmacsがコンパイルされた場合、ファイルが存在しないかアクセス不能な場合、またはその他の理由によりEmacsがACLエントリーを判断できない場合、リターン値はnilである。

Function: file-selinux-context filename

この関数は、ファイルfilenameのSELinuxコンテキストを、(user role type range)という形式のリストでリターンする。リストの要素は、そのコンテキストのユーザー、ロール、タイプ、レンジを文字列として表す値である。これらの実際の意味についての詳細は、SELinuxのドキュメントを参照のこと。リターン値は、set-file-selinux-contextがcontext引数でとるのと同じ形式である(ファイルの名前と属性の変更を参照)。

SELinuxサポートなしでEmacsがコンパイルされた場合、ファイルが存在しないかアクセス不能な場合、またはシステムがSELinuxをサポートしない場合、リターン値は(nil nil nil nil)である。

Function: file-extended-attributes filename

この関数は、Emacsが認識するファイルfilenameの拡張属性をalistでリターンする。現在のところ、この関数はACLとSELinuxの両方を取得するための便利な方法としての役目を果たす。他のファイルに同じファイルアクセス属性を適用するために、リターンされたalistを2つ目の引数としてset-file-extended-attributesを呼び出すことができる(ファイルの名前と属性の変更を参照)。

要素のうちの1つは(acl . acl)で、aclはfile-aclがリターンするのと同じ形式である。

他の要素は(selinux-context . context)で、contextはfile-selinux-contextがリターンするのと同じ形式である。

25.6.6 標準的な場所へのファイルの配置

このセクションでは、ディレクトリーのリスト(パス(path))からファイルを検索したり、標準の実行可能ファイル用ディレクトリーから実行可能ファイルを検索する方法を説明します。

ユーザー固有の設定ファイル(configuration file)の検索については、標準的なファイル名の関数locate-user-emacs-fileを参照してください。

Function: locate-file filename path &optional suffixes predicate

この関数は、pathで与えられるディレクトリーリスト内で、filenameという名前のファイルを検索して、suffixes内のサフィックスの検索を試みる。そのようなファイルが見つかった場合はファイルの絶対ファイル名(絶対ファイル名と相対ファイル名を参照)をリターンし、それ以外はnilをリターンする。

オプション引数suffixesは、検索時にfilenameに追加するファイル名サフィックスのリストを与える。locate-fileは、検索するディレクトリーごとに、それらのサフィックスを試みる。suffixesがnil、または("")の場合は、サフィックスなしで、filenameだけがそのまま使用される。suffixesの典型的な値はexec-suffixes(サブプロセスを作成する関数を参照)、load-suffixes、load-file-rep-suffixes、および関数get-load-suffixes(ロードでの拡張子を参照)である。

実行可能プログラムを探すときはexec-path(サブプロセスを作成する関数を参照)、Lispファイルを探すときはload-path(ライブラリー検索を参照)がpathの典型的な値である。filenameが絶対ファイル名の場合、pathは効果がないが、サフィックスにたいするsuffixesは依然として試行される。

オプション引数predicateが非nilの場合、それは候補ファイルが適切かどうかテストする述語関数を指定する。述語関数には、単一の引数として候補ファイル名が渡される。predicateがnil、または省略された場合は、述語としてfile-readable-pを使用する。file-executable-pやfile-directory-pなど、その他の有用な述語については、ファイル種別の区別を参照のこと。

This function will normally skip directories, so if you want it to find directories, make sure the predicate function returns dir-ok for them. For example:

(locate-file "html" '("/var/www" "/srv") nil
             (lambda (f) (if (file-directory-p f) 'dir-ok)))

互換性のために、predicateにはexecutable、readable、writable、exists、またはこれらシンボルの1つ以上のリストも指定できる。

Function: executable-find program: この関数は、programという名前の実行可能ファイルを検索して、その実行可能ファイルの絶対ファイル名と、もしあればファイル名の拡張子も含めてリターンする。ファイルが見つからない場合は、nilをリターンする。この関数は、exec-path内のすべてのディレクトリーを検索し、exec-suffixes内のすべてのファイル名拡張子の検索も試みる(サブプロセスを作成する関数を参照)。

25.7 ファイルの名前と属性の変更

The functions in this section rename, copy, delete, link, and set the modes (permissions) of files. Typically, they signal a file-error error if they fail to perform their function, reporting the system-dependent error message that describes the reason for the failure. If they fail because a file is missing, they signal a file-missing error instead.

For performance, the operating system may cache or alias changes made by these functions instead of writing them immediately to secondary storage. See section Files and Secondary Storage.

In the functions that have an argument newname, if this argument is a directory name it is treated as if the nondirectory part of the source name were appended. Typically, a directory name is one that ends in ‘/’ (see section ディレクトリーの名前). For example, if the old name is a/b/c, the newname d/e/f/ is treated as if it were d/e/f/c. This special treatment does not apply if newname is not a directory name but names a file that is a directory; for example, the newname d/e/f is left as-is even if d/e/f happens to be a directory.

newnameという引数をもつ関数では、newnameという名前のファイルが既に存在する場合の振る舞いは、引数ok-if-already-existsの値に依存します。

ok-if-already-existsがnilの場合は、file-already-existsエラーがシグナルされる。
ok-if-already-existsが数字の場合は、確認を求める。
ok-if-already-existsが他の値の場合は、確認なしで古いファイルを置き換える。

Command: add-name-to-file oldname newname &optional ok-if-already-exists

This function gives the file named oldname the additional name newname. This means that newname becomes a new hard link to oldname.

If newname is a symbolic link, its directory entry is replaced, not the directory entry it points to. If oldname is a symbolic link, this function might or might not follow the link; it does not follow the link on GNU platforms. If oldname is a directory, this function typically fails, although for the superuser on a few old-fashioned non-GNU platforms it can succeed and create a filesystem that is not tree-structured.

以下の例の最初の部分として、2つのファイルfooとfoo3をリストする。

$ ls -li fo*
81908 -rw-rw-rw- 1 rms rms 29 Aug 18 20:32 foo
84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3

ここで、add-name-to-fileを呼び出してハードリンクを作成し、再度ファイルをリストする。このリストには、1つのファイルにたいして2つの名前fooとfoo2が表示される。

(add-name-to-file "foo" "foo2")
     ⇒ nil

$ ls -li fo*
81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo
81908 -rw-rw-rw- 2 rms rms 29 Aug 18 20:32 foo2
84302 -rw-rw-rw- 1 rms rms 24 Aug 18 20:31 foo3

最後に以下を評価する:

(add-name-to-file "foo" "foo3" t)

そして、ファイルを再度リストする。今度は1つのファイルにたいして3つの名前foo、foo2、foo3がある。foo3の古いコンテンツは失われた。

(add-name-to-file "foo1" "foo3")
     ⇒ nil

$ ls -li fo*
81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo
81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo2
81908 -rw-rw-rw- 3 rms rms 29 Aug 18 20:32 foo3

この関数は、1つのファイルにたいして複数の名前をもつことが許されないオペレーティングシステムでは無意味である。いくつかのシステムでは、かわりにファイルをコピーすることにより複数の名前を実装している。

ファイルの属性のfile-nlinksも参照のこと。

Command: rename-file filename newname &optional ok-if-already-exists

このコマンドは、filenameをnewnameにリネームする。

If filename has additional names aside from filename, it continues to have those names. In fact, adding the name newname with add-name-to-file and then deleting filename has the same effect as renaming, aside from momentary intermediate states and treatment of errors, directories and symbolic links.

This command does not follow symbolic links. If filename is a symbolic link, this command renames the symbolic link, not the file it points to. If newname is a symbolic link, its directory entry is replaced, not the directory entry it points to.

This command does nothing if filename and newname are the same directory entry, i.e., if they refer to the same parent directory and give the same name within that directory. Otherwise, if filename and newname name the same file, this command does nothing on POSIX-conforming systems, and removes filename on some non-POSIX systems.

If newname exists, then it must be an empty directory if oldname is a directory and a non-directory otherwise.

Command: copy-file oldname newname &optional ok-if-already-exists time preserve-uid-gid preserve-extended-attributes

This command copies the file oldname to newname. An error is signaled if oldname is not a regular file. If newname names a directory, it copies oldname into that directory, preserving its final name component.

This function follows symbolic links, except that it does not follow a dangling symbolic link to create newname.

timeが非nilの場合、この関数は新たなファイルにたいして、古いファイルと同じ最終変更時刻を与える(これはいくつかの限られたオペレーティングシステムでのみ機能する)。時刻のセットでエラーが発生した場合、copy-fileはfile-date-errorエラーをシグナルする。インタラクティブに呼び出された場合、プレフィックス引数はtimeにたいして非nil値を指定する。

引数preserve-uid-gidがnilの場合は、新たなファイルのユーザーおよびグループの所有権の決定を、オペレーティングシステムに委ねる(通常はEmacsを実行中のユーザーである)。preserve-uid-gidが非nilの場合は、そのファイルのユーザーとグループの所有権のコピーを試みる。これはいくつかのオペレーティングシステムで、かつそれを行うための正しいパーミッションをもつ場合のみ機能する。

オプション引数preserve-permissionsが非nilの場合、この関数はoldnameのファイルモード(または“パーミッション”)、同様にACL(Access Control List)とSELinuxコンテキストをnewnameにコピーする。ファイルの情報を参照のこと。

それ以外では、newnameが既存ファイルならファイルモードは変更されず、新たに作成された場合はデフォルトのファイルパーミッション(以下のset-default-file-modesを参照)によりマスクされる。どちらの場合も、ACLまたはSELinuxコンテキストはコピーされない。

Command: make-symbolic-link target newname &optional ok-if-already-exists

This command makes a symbolic link to target, named newname. This is like the shell command ‘ln -s target newname’. The target argument is treated only as a string; it need not name an existing file. If ok-if-already-exists is an integer, indicating interactive use, then leading ‘~’ is expanded and leading ‘/:’ is stripped in the target string.

If target is a relative file name, the resulting symbolic link is interpreted relative to the directory containing the symbolic link. See section 絶対ファイル名と相対ファイル名.

If both target and newname have remote file name syntax, and if both remote identifications are equal, the symbolic link points to the local file name part of target.

この関数は、シンボリックリンクをサポートしないシステムでは利用できない。

Command: delete-file filename &optional trash

This command deletes the file filename. If the file has multiple names, it continues to exist under the other names. If filename is a symbolic link, delete-file deletes only the symbolic link and not its target.

A suitable kind of file-error error is signaled if the file does not exist, or is not deletable. (On GNU and other POSIX-like systems, a file is deletable if its directory is writable.)

オプション引数trashが非nil、かつ変数delete-by-moving-to-trashが非nilの場合、このコマンドはファイルを削除するかわりに、システムのTrash(ゴミ箱)にファイルを移動する。Miscellaneous File Operations in The GNU Emacs Manualを参照のこと。インタラクティブに呼び出された際は、プレフィックス引数がない場合trashはt、それ以外はnilである。

ディレクトリーの作成・コピー・削除のdelete-directoryも参照のこと。

Command: set-file-modes filename mode

This function sets the file mode (or permissions) of filename to mode. This function follows symbolic links.

非インタラクティブに呼び出された場合、modeは整数でなければならない。その整数の下位12ビットだけが使用される。ほとんどのシステムでは、意味があるのは下位9ビットだけである。modeを入力刷る、Lisp構文を使用できる。たとえば、

(set-file-modes #o644)

これは、そのファイルが所有者により読み取りと書き込み、グループメンバーにより読み取り、その他のユーザーにより読み取り可能であることを指定する。モードビットの仕様の説明は、File permissions in The GNU Coreutils Manualを参照のこと。

インタラクティブに呼び出された場合、modeはread-file-modes(以下参照)を使用してミニバッファーから読み取られる。この場合、ユーザーは整数、またはパーミッションをシンボルで表現する文字列をタイプできる。

ファイルのパーミッションをリターンする関数file-modesについては、ファイルの属性を参照のこと。

Function: set-default-file-modes mode

This function sets the default permissions for new files created by Emacs and its subprocesses. Every file created with Emacs initially has these permissions, or a subset of them (write-region will not grant execute permissions even if the default file permissions allow execution). On GNU and other POSIX-like systems, the default permissions are given by the bitwise complement of the ‘umask’ value, i.e. each bit that is set in the argument mode will be reset in the default permissions with which Emacs creates files.

引数modeは上記のset-file-modesと同様、パーミッションを指定する整数であること。下位9ビットだけに意味がある。

デフォルトのファイルパーミッションは、既存ファイルの変更されたバージョンを保存する際は効果がない。ファイルの保存では、既存のパーミッションが保持される。

Macro: with-file-modes mode body…

This macro evaluates the body forms with the default permissions for new files temporarily set to modes (whose value is as for set-file-modes above). When finished, it restores the original default file permissions, and returns the value of the last form in body.

This is useful for creating private files, for example.

Function: default-file-modes: この関数は、デフォルトのファイルモードを整数でリターンする。

Function: read-file-modes &optional prompt base-file

この関数は、ミニバッファーからファイルモードビットのセットを読み取る。1つ目のオプション引数promptは非デフォルトのプロンプトを指定する。2つ目のオプション引数base-fileは、ユーザーが既存ファイルのパーミッションに相対的なモードビット指定をタイプした場合に、この関数がリターンするモードビッの元となる権限をもつファイルの名前を指定する。

ユーザー入力が8進数で表される場合、この関数はその数字をリターンする。それが"u=rwx"のようなモードビットの完全なシンボル指定の場合、この関数はfile-modes-symbolic-to-numberを使用して、それを等価な数字に変換し、結果をリターンする。"o+g"のように相対的な指定の場合、その指定の元となるパーミッションは、base-fileのモードビットから取得される。base-fileが省略、またはnilの場合、この関数は元となるモードビットとして0を使用する。完全指定および相対指定は、"u+r,g+rx,o+r,g-w"のように組み合わせることができる。ファイルモード指定の説明は、File permissions in The GNU Coreutils Manualを参照のこと。

Function: file-modes-symbolic-to-number modes &optional base-modes: この関数は、modes内のシンボルによるファイルモード指定を、等価な整数に変換する。シンボル指定が既存ファイルにもとづく場合は、オプション引数base-modesからそのファイルのモードビットが取得される。その引数が省略、またはnilの場合は、0(すべてのアクセスが許可されない)がデフォルトになる。

Function: set-file-times filename &optional time: This function sets the access and modification times of filename to time. The return value is t if the times are successfully set, otherwise it is nil. time defaults to the current time and must be a time value (see section 時刻).

Function: set-file-extended-attributes filename attribute-alist: This function sets the Emacs-recognized extended file attributes for filename. The second argument attribute-alist should be an alist of the same form returned by file-extended-attributes. The return value is t if the attributes are successfully set, otherwise it is nil. See section 拡張されたファイル属性.

Function: set-file-selinux-context filename context

この関数は、filenameにたいするSELinuxセキュリティコンテキストにcontextをセットする。context引数は、各要素が文字列であるような(user role type range)というリストであること。拡張されたファイル属性を参照されたい。

この関数は、filenameのSELinuxコンテキストのセットに成功した場合はtをリターンする。コンテキストがセットされなかった場合(SELinuxが無効、またはEmacsがSELinuxサポートなしでコンパイルされた場合等)は、nilをリターンする。

Function: set-file-acl filename acl

この関数は、filenameにたいするACLにaclをセットする。acl引数は、関数file-aclがリターンするのと同じ形式であること。拡張されたファイル属性を参照されたい。

この関数はfilenameのACLのセットに成功したらt、それ以外はnilをリターンする。

25.8 Files and Secondary Storage

After Emacs changes a file, there are two reasons the changes might not survive later failures of power or media, both having to do with efficiency. First, the operating system might alias written data with data already stored elsewhere on secondary storage until one file or the other is later modified; this will lose both files if the only copy on secondary storage is lost due to media failure. Second, the operating system might not write data to secondary storage immediately, which will lose the data if power is lost.

Although both sorts of failures can largely be avoided by a suitably configured file system, such systems are typically more expensive or less efficient. In more-typical systems, to survive media failure you can copy the file to a different device, and to survive a power failure you can use the write-region function with the write-region-inhibit-fsync variable set to nil. See section ファイルの書き込み.

25.9 ファイルの名前

ファイルは一般的に名前で参照され、Emacsでも他と同様です。Emacsでは、ファイル名は文字列で表現されます。ファイルを操作する関数はすべて、ファイル名引数に文字列を期待します。

ファイル自体の操作に加えて、Emacs Lispプログラムでファイル名を処理する必要(ファイル名の一部を取得して、関連するファイル名構築にその一部を使用する等)がしばしばあります。このセクションでは、ファイル名を扱う方法を説明します。

このセクションの関数は実際にファイルにアクセスする訳ではないので、既存のファイルやディレクトリーを参照しないファイル名を処理できます。

On MS-DOS and MS-Windows, these functions (like the function that actually operate on files) accept MS-DOS or MS-Windows file-name syntax, where backslashes separate the components, as well as POSIX syntax; but they always return POSIX syntax. This enables Lisp programs to specify file names in POSIX syntax and work properly on all systems without change.¹³

25.9.1 ファイル名の構成要素		ファイル名のディレクトリー部分と、それ以外。
25.9.2 絶対ファイル名と相対ファイル名		カレントディレクトリーにたいして相対的なファイル名。
25.9.3 ディレクトリーの名前		ディレクトリーとしてのディレクトリー名と、ファイルとしてのファイル名の違い。
25.9.4 ファイル名を展開する関数		相対ファイル名から絶対ファイル名への変換。
25.9.5 一意なファイル名の生成		一時ファイル用の名前の生成。
25.9.6 ファイル名の補完		与えられたファイル名にたいする補完を探す。
25.9.7 標準的なファイル名		パッケージが固定されたファイル名を使用する際に、種々のオペレーティングシステムをシンプルに処理する方法。

25.9.1 ファイル名の構成要素

オペレーティングシステムは、ファイルをディレクトリーにグループ化します。あるファイルを指定するためには、ディレクトリーと、そのディレクトリー内でのファイルの名前を指定しなければなりません。それゆえ、Emacsはファイル名をディレクトリー名パートと非ディレクトリー(またはディレクトリー内ファイル名)パートという、2つの主要パートから判断します。どちらのパートも空の場合があり得ます。これら2つのパートを結合することにより、元のファイル名が再作成されます。

ほとんどのシステムでは、最後のスラッシュ(MS-DOSおよびMS-Windowsではバックスラッシュも許される)までのすべてがディレクトリーパートです。残りが非ディレクトリーパートです。

ある目的のために、非ディレクトリーパートはさらに正式名称(the name proper)とバージョン番号に細分されます。ほとんどのシステムでは、名前にバージョン番号をもつのは、バックアップファイルだけです。

Function: file-name-directory filename

この関数は、filenameのディレクトリーパートをディレクトリー名(ディレクトリーの名前を参照)としてリターンする。filenameがディレクトリーパートを含まない場合は、nilをリターンする。

On GNU and other POSIX-like systems, a string returned by this function always ends in a slash. On MS-DOS it can also end in a colon.

(file-name-directory "lewis/foo")  ; GNU example
     ⇒ "lewis/"

(file-name-directory "foo")        ; GNU example
     ⇒ nil

Function: file-name-nondirectory filename

この関数は、filenameの非ディレクトリーパートをリターンする。

(file-name-nondirectory "lewis/foo")
     ⇒ "foo"

(file-name-nondirectory "foo")
     ⇒ "foo"

(file-name-nondirectory "lewis/")
     ⇒ ""

Function: file-name-sans-versions filename &optional keep-backup-version

この関数は、任意のファイルバージョン番号、バックアップバージョン番号、末尾のチルダを取り除いてfilenameをリターンする。

keep-backup-versionが非nilの場合は、ファイルシステムなどが理解するような真のファイルバージョン番号は破棄されるが、バックアップバージョン番号は保持される。

(file-name-sans-versions "~rms/foo.~1~")
     ⇒ "~rms/foo"

(file-name-sans-versions "~rms/foo~")
     ⇒ "~rms/foo"

(file-name-sans-versions "~rms/foo")
     ⇒ "~rms/foo"

Function: file-name-extension filename &optional period

This function returns filename’s final extension, if any, after applying file-name-sans-versions to remove any version/backup part. The extension, in a file name, is the part that follows the last ‘.’ in the last name component (minus any version/backup part).

This function returns nil for extensionless file names such as foo. It returns "" for null extensions, as in foo.. If the last component of a file name begins with a ‘.’, that ‘.’ doesn’t count as the beginning of an extension. Thus, .emacs’s extension is nil, not ‘.emacs’.

periodが非nilの場合、拡張子を区切るピリオドもリターン値に含まれるようにななる。その場合、もしfilenameが拡張子をもたないなら、リターン値は""である。

Function: file-name-sans-extension filename

この関数は、もしあればfilenameから拡張子を除いてリターンする。もしバージョン番号またはバックアップ番号があるなら、ファイルが拡張子をもつ場合のみ、それを削除する。たとえば、

(file-name-sans-extension "foo.lose.c")
     ⇒ "foo.lose"
(file-name-sans-extension "big.hack/foo")
     ⇒ "big.hack/foo"
(file-name-sans-extension "/my/home/.emacs")
     ⇒ "/my/home/.emacs"
(file-name-sans-extension "/my/home/.emacs.el")
     ⇒ "/my/home/.emacs"
(file-name-sans-extension "~/foo.el.~3~")
     ⇒ "~/foo"
(file-name-sans-extension "~/foo.~3~")
     ⇒ "~/foo.~3~"

最後の2つの例の‘.~3~’は、拡張子ではなくバックアップ番号であることに注意。

Function: file-name-base &optional filename

この関数は、file-name-sans-extensionとfile-name-nondirectoryを組み合わせたものである。たとえば、

(file-name-base "/my/home/foo.c")
    ⇒ "foo"

filename引数のデフォルトは、buffer-file-nameである。

25.9.2 絶対ファイル名と相対ファイル名

All the directories in the file system form a tree starting at the root directory. A file name can specify all the directory names starting from the root of the tree; then it is called an absolute file name. Or it can specify the position of the file in the tree relative to a default directory; then it is called a relative file name. On GNU and other POSIX-like systems, after any leading ‘~’ has been expanded, an absolute file name starts with a ‘/’ (see abbreviate-file-name), and a relative one does not. On MS-DOS and MS-Windows, an absolute file name starts with a slash or a backslash, or with a drive specification ‘x:/’, where x is the drive letter.

Function: file-name-absolute-p filename

This function returns t if file filename is an absolute file name or begins with ‘~’, nil otherwise.

(file-name-absolute-p "~rms/foo")
     ⇒ t

(file-name-absolute-p "rms/foo")
     ⇒ nil

(file-name-absolute-p "/user/rms/foo")
     ⇒ t

Given a possibly relative file name, you can expand any leading ‘~’ and convert the result to an absolute name using expand-file-name (see section ファイル名を展開する関数). This function converts absolute file names to relative names:

Function: file-relative-name filename &optional directory

この関数は、directory(絶対ディレクトリー名またはディレクトリーファイル名)から相対的な結果となると仮定して、filenameと等価な相対ファイル名のリターンを試みる。directoryが省略、またはnilの場合、カレントバッファーのデフォルトディレクトリーがデフォルトとなる。

絶対ファイル名がデバイス名で始まるオペレーティングシステムが、いくつか存在する。そのようなシステムでは、2つの異なるデバイス名から開始されるfilenameは、directoryにもとづく等価な相対ファイル名をもたない。この場合、file-relative-nameは絶対形式でfilenameをリターンする。

(file-relative-name "/foo/bar" "/foo/")
     ⇒ "bar"
(file-relative-name "/foo/bar" "/hack/")
     ⇒ "../foo/bar"

25.9.3 ディレクトリーの名前

A directory name is a string that must name a directory if it names any file at all. A directory is actually a kind of file, and it has a file name (called the directory file name, which is related to the directory name but is typically not identical. (This is not quite the same as the usual POSIX terminology.) These two names for the same entity are related by a syntactic transformation. On GNU and other POSIX-like systems, this is simple: to obtain a directory name, append a ‘/’ to a directory file name that does not already end in ‘/’. On MS-DOS the relationship is more complicated.

The difference between a directory name and a directory file name is subtle but crucial. When an Emacs variable or function argument is described as being a directory name, a directory file name is not acceptable. When file-name-directory returns a string, that is always a directory name.

The following two functions convert between directory names and directory file names. They do nothing special with environment variable substitutions such as ‘$HOME’, and the constructs ‘~’, ‘.’ and ‘..’.

Function: file-name-as-directory filename

This function returns a string representing filename in a form that the operating system will interpret as the name of a directory (a directory name). On most systems, this means appending a slash to the string (if it does not already end in one).

(file-name-as-directory "~rms/lewis")
     ⇒ "~rms/lewis/"

Function: directory-name-p filename: This function returns non-nil if filename ends with a directory separator character. This is the forward slash ‘/’ on GNU and other POSIX-like systems; MS-Windows and MS-DOS recognize both the forward slash and the backslash ‘\’ as directory separators.

Function: directory-file-name dirname

This function returns a string representing dirname in a form that the operating system will interpret as the name of a file (a directory file name). On most systems, this means removing the final directory separators from the string, unless the string consists entirely of directory separators.

(directory-file-name "~lewis/")
     ⇒ "~lewis"

ディレクトリーにたいしては、concatを使用して相対ファイルと組み合わせることができます:

(concat dirname relfile)

これを行う前に、ファイル名が相対的であるか確認してください。絶対ファイル名を使用した場合、結果は構文的に不正になるか、間違ったファイルを参照する可能性があります。

ディレクトリーファイル名作成にこのような組み合わせを使用したい場合は、最初にfile-name-as-directoryを使用して、それをディレクトリー名に変換しなければなりません:

(concat (file-name-as-directory dirfile) relfile)

以下のような、手動によるスラッシュの結合を試みてはなりません

;;; 間違い!
(concat dirfile "/" relfile)

なぜなら、これには可搬性がないからです。常にfile-name-as-directoryを使用してください。

To avoid the issues mentioned above, or if the dirname value might be nil (for example, from an element of load-path), use:

(expand-file-name relfile dirname)

However, expand-file-name expands leading ‘~’ in relfile, which may not be what you want. See section ファイル名を展開する関数.

ディレクトリー名をディレクトリーの省略名に変換するには、以下の関数を使用します:

Function: abbreviate-file-name filename

この関数は、filenameの省略された形式をリターンする。これはdirectory-abbrev-alist(see File Aliases in The GNU Emacs Manual)で指定される省略形を適用した後、引数のファイル名がユーザーのホームディレクトリー、またはそのサブディレクトリーにある場合は、それを‘~’に置き換える。ホームディレクトリーがルートディレクトリーの場合、多くのシステムでは結果が短縮されないので、‘~’で置き換えない。

これは名前の一部であるような省略形さえも認識するので、ディレクトリー名とファイル名にも使用できる。

25.9.4 ファイル名を展開する関数

Expanding a file name means converting a relative file name to an absolute one. Since this is done relative to a default directory, you must specify the default directory as well as the file name to be expanded. It also involves expanding abbreviations like ~/ (abbreviate-file-nameを参照)、の展開、および./やname/../のような冗長さの排除も行います。も展開します。

Function: expand-file-name filename &optional directory

This function converts filename to an absolute file name. If directory is supplied, it is the default directory to start with if filename is relative and does not start with ‘~’. (The value of directory should itself be an absolute directory name or directory file name; it may start with ‘~’.) Otherwise, the current buffer’s value of default-directory is used. For example:

(expand-file-name "foo")
     ⇒ "/xcssun/users/rms/lewis/foo"

(expand-file-name "../foo")
     ⇒ "/xcssun/users/rms/foo"

(expand-file-name "foo" "/usr/spool/")
     ⇒ "/usr/spool/foo"

If the part of filename before the first slash is ‘~’, it expands to the value of the HOME environment variable (usually your home directory). If the part before the first slash is ‘~user’ and if user is a valid login name, it expands to user’s home directory. If you do not want this expansion for a relative filename that might begin with a literal ‘~’, you can use (concat (file-name-as-directory directory) filename) instead of (expand-file-name filename directory).

‘.’または‘..’を含むファイル名は、正規化形式に簡略化される:

(expand-file-name "bar/../foo")
     ⇒ "/xcssun/users/rms/lewis/foo"

出力に‘..’コンポーネントが残り得る場合もある:

(expand-file-name "../home" "/")
     ⇒ "/../home"

This is for the sake of filesystems that have the concept of a superroot above the root directory /. On other filesystems, /../ is interpreted exactly the same as /.

expand-file-nameは環境変数を展開しないことに注意。substitute-in-file-nameだけが、それを行う。

(expand-file-name "$HOME/foo")
     ⇒ "/xcssun/users/rms/lewis/$HOME/foo"

expand-file-nameは、あらゆる階層においてシンボリックリンクをフォローしないことにも注意。これは‘..’の扱いがfile-truenameとexpand-file-nameで異なることに起因する。‘/tmp/bar’がディレクトリー‘/tmp/foo/bar’にたいするシンボリックリンクであると仮定すると:

(file-truename "/tmp/bar/../myfile")
     ⇒ "/tmp/foo/myfile"

(expand-file-name "/tmp/bar/../myfile")
     ⇒ "/tmp/myfile"

直接間接を問わず、事前にexpand-file-nameを呼び出さずに‘..’に先行するシンボリックリンクをフォローする必要があるかもしれない場合は、それを呼び出さずに確実にfile-truenameを呼び出すべきである。本当の名前を参照のこと。

Variable: default-directory

このバッファーローカル変数の値は、カレントバッファーにたいするデフォルトディレクトリーである。これは絶対ディレクトリー名であること。これは‘~’で始まるかもしれない。この変数は、すべてのバッファーにおいてバッファーローカルである。

2つ目の引数がnilの場合、expand-file-nameはデフォルトディレクトリーを使用する。

値は常にスラッシュで終わる文字列である。

default-directory
     ⇒ "/user/lewis/manual/"

Function: substitute-in-file-name filename

This function replaces environment variable references in filename with the environment variable values. Following standard Unix shell syntax, ‘$’ is the prefix to substitute an environment variable value. If the input contains ‘$$’, that is converted to ‘$’; this gives the user a way to quote a ‘$’.

環境変数名は‘$’の後に続く一連の英数字(アンダースコアを含む)である。‘$’の後続文字が、‘{’の場合はマッチする‘}’までのすべてが変数名である。

substitute-in-file-nameにより生成された出力でsubstitute-in-file-nameを呼び出すと、不正な結果となる傾向がある。たとえば、単一の‘$’をクォートするための‘$$’の使用は正しく機能しないだろうし、環境変数値の中の‘$’は再帰的な置換を導くだろう。したがって、この関数を呼び出して、出力をこの関数に渡すプログラムは、その後の不正な結果を防ぐために、すべての‘$’文字を二重化する必要がある。

Here we assume that the environment variable HOME, which holds the user’s home directory, has value ‘/xcssun/users/rms’.

(substitute-in-file-name "$HOME/foo")
     ⇒ "/xcssun/users/rms/foo"

置き換え後は、‘/’の直後に‘~’や別の‘/’が出現した場合、この関数は、‘/’の前にあるすべてを無視する。

(substitute-in-file-name "bar/~/foo")
     ⇒ "~/foo"

(substitute-in-file-name "/usr/local/$HOME/foo")
     ⇒ "/xcssun/users/rms/foo"
     ;; /usr/local/は破棄された

Sometimes, it is not desired to expand file names. In such cases, the file name can be quoted to suppress the expansion, and to handle the file name literally. Quoting happens by prefixing the file name with ‘/:’.

Macro: file-name-quote name

This macro adds the quotation prefix ‘/:’ to the file name. For a local file name, it prefixes name with ‘/:’. If name is a remote file name, the local part of name is quoted. If name is already a quoted file name, name is returned unchanged.

(substitute-in-file-name (file-name-quote "bar/~/foo"))
     ⇒ "/:bar/~/foo"

(substitute-in-file-name (file-name-quote "/ssh:host:bar/~/foo"))
     ⇒ "/ssh:host:/:bar/~/foo"

The macro cannot be used to suppress file name handlers from magic file names (see section 特定のファイル名の“Magic”の作成).

Macro: file-name-unquote name: This macro removes the quotation prefix ‘/:’ from the file name, if any. If name is a remote file name, the local part of name is unquoted.

Macro: file-name-quoted-p name: This macro returns non-nil, when name is quoted with the prefix ‘/:’. If name is a remote file name, the local part of name is checked.

25.9.5 一意なファイル名の生成

一時ファイルに書き込む必要があるプログラムが、いくつかあります。以下は、そのようなファイルを構築する、便利な方法です:

(make-temp-file name-of-application)

make-temp-fileの役目は、2人の異なるユーザー、またはジョブが、完全に一致する名前のファイルの使用を防ぐことです。

Function: make-temp-file prefix &optional dir-flag suffix text

This function creates a temporary file and returns its name. Emacs creates the temporary file’s name by adding to prefix some random characters that are different in each Emacs job. The result is guaranteed to be a newly created file, containing text if that’s given as a string and empty otherwise. On MS-DOS, this function can truncate the string prefix to fit into the 8+3 file-name limits. If prefix is a relative file name, it is expanded against temporary-file-directory.

(make-temp-file "foo")
     ⇒ "/tmp/foo232J6v"

make-temp-fileがリターンした際、一時ファイルは空で作成される。この時点で、そのファイルに意図するコンテンツを書き込むべきである。

dir-flagがnilの場合、make-temp-fileは空のファイルのかわりに、空のディレクトリーを作成する。これはディレクトリー名ではなく、ディレクトリーのファイル名をリターンする。ディレクトリーの名前を参照のこと。

suffixが非nilの場合、make-temp-fileはそれをファイル名の最後に追加する。

If text is a string, make-temp-file inserts it in the file.

同じEmacs内で実行される異なるライブラリー間での競合を防ぐために、make-temp-fileを使用する各Lispプログラムがプログラム自身のprefixを使用するべきである。prefixの最後に追加される数字は、異なるEmacsジョブ内で実行される、同じアプリケーションを区別する。追加される文字により、同一のEmacsジョブ内でも、多数の名前を区別することが可能になる。

一時ファイル用のデフォルトディレクトリーは、変数temporary-file-directoryにより制御されます。この変数により、すべての一時ファイルにたいして、ユーザーがディレクトリーを指定する、一貫した方法が与えられます。small-temporary-file-directoryが非nilの場合は、かわりにそれを使うプログラムもいくつかあります。これを使う場合は、make-temp-fileを呼び出す前に、正しいディレクトリーにたいしてプレフィックスを展開するべきです。

User Option: temporary-file-directory

この変数は、一時ファイル作成用のディレクトリー名を指定する。値はディレクトリー名であるべきだが、もし値がディレクトリーのファイル名(ディレクトリーの名前を参照)ならば、Lispプログラムがかわりに対処すればよい。expand-file-nameの2つ目の引数としてその値を使用するのは、それを達成するよい方法である。

デフォルト値は、オペレーティングシステムにたいして適切な方法により決定される。これは環境変数TMPDIR、TMP、TEMPにもとづき、これらの変数が定義されていなければ、システム依存の名前にフォールバックする。

一時ファイルの作成にmake-temp-fileを使用しない場合でも、一時ファイルを置くディレクトリーを判断するために、依然としてこの変数を使用するべきである。しかし、一時ファイルが小さくなることを求める場合は、small-temporary-file-directoryが非nilならば、それを使用するべきである。

User Option: small-temporary-file-directory

この変数は、小さいかもしれない特定の一時ファイル作成用のディレクトリー名を指定する。

小さくなるかもしれない一時ファイルに書き込みたい場合は、以下のようにディレクトリーを計算するべきである:

(make-temp-file
  (expand-file-name prefix
                    (or small-temporary-file-directory
                        temporary-file-directory)))

Function: make-temp-name base-name

This function generates a string that might be a unique file name. The name starts with base-name, and has several random characters appended to it, which are different in each Emacs job. It is like make-temp-file except that (i) it just constructs a name and does not create a file, (ii) base-name should be an absolute file name that is not magic, and (iii) if the returned file name is magic, it might name an existing file. See section 特定のファイル名の“Magic”の作成.

警告: この関数を使用するべきではない。かわりにmake-temp-fileを使用すること! この関数は、競合状態の影響を受けやすい。make-temp-name呼び出しと一時ファイル作成のタイムラグは、セキュリティーホールとなる場合があるかもしれない。

Sometimes, it is necessary to create a temporary file on a remote host or a mounted directory. The following two functions support this.

Function: make-nearby-temp-file prefix &optional dir-flag suffix

This function is similar to make-temp-file, but it creates a temporary file as close as possible to default-directory. If prefix is a relative file name, and default-directory is a remote file name or located on a mounted file systems, the temporary file is created in the directory returned by the function temporary-file-directory. Otherwise, the function make-temp-file is used. prefix, dir-flag and suffix have the same meaning as in make-temp-file.

(let ((default-directory "/ssh:remotehost:"))
  (make-nearby-temp-file "foo"))
     ⇒ "/ssh:remotehost:/tmp/foo232J6v"

Function: temporary-file-directory: The directory for writing temporary files via make-nearby-temp-file. In case of a remote default-directory, this is a directory for temporary files on that remote host. If such a directory does not exist, or default-directory ought to be located on a mounted file system (see mounted-file-systems), the function returns default-directory. For a non-remote and non-mounted default-directory, the value of the variable temporary-file-directory is returned.

In order to extract the local part of the path name from a temporary file, file-local-name could be used.

25.9.6 ファイル名の補完

このセクションでは、ファイル名を補完するための、低レベルサブルーチンについて説明します。より高レベルの関数については、ファイル名の読み取りを参照してください。

Function: file-name-all-completions partial-filename directory

この関数は、ディレクトリーdirectory内で、partial-filenameで始まる名前のファイルにたいして、すべての補完可能なリストをリターンする。補完の順番はそのディレクトリー内でのファイル順序であり、これは予測不能で何の情報ももたない。

引数partial-filenameは非ディレクトリーパートを含むファイル名でなければならず、スラッシュ(いくつかのシステムではバックスラッシュ)が含まれていてはならない。directoryが絶対ディレクトリーでない場合は、directoryの前にカレントバッファーのデフォルトディレクトリーが追加される。

以下の例では、~rms/lewisがカレントデフォルトディレクトリーで、名前が‘f’で始まる5つのファイルfoo、file~、file.c、file.c.~1~、file.c.~2~があるものとする:

(file-name-all-completions "f" "")
     ⇒ ("foo" "file~" "file.c.~2~"
                "file.c.~1~" "file.c")

(file-name-all-completions "fo" "")
     ⇒ ("foo")

Function: file-name-completion filename directory &optional predicate

この関数は、ディレクトリーdirectory内で、ファイル名filenameを補完する。これはディレクトリーdirectory内で、filenameで始まるすべてのファイル名にたいして、最長の共通プレフィックスをリターンする。predicateが非nilの場合は、この関数を1引数で呼び出して絶対ファイル名に展開後、predicateを満足しない補完候補を無視する。

マッチが1つだけ存在し、かつfilenameが正確にそれにマッチする場合、関数はtをリターンする。関数は、ディレクトリーdirectoryがfilenameで始まる名前のファイルを含まない場合は、nilをリターンする。

(file-name-completion "fi" "")
     ⇒ "file"

(file-name-completion "file.c.~1" "")
     ⇒ "file.c.~1~"

(file-name-completion "file.c.~1~" "")
     ⇒ t

(file-name-completion "file.c.~3" "")
     ⇒ nil

User Option: completion-ignored-extensions

file-name-completionは通常、このリスト内の任意の文字列で終わるファイル名を無視する。すべての可能な補完がこれらのサフィックスのいずれか1つで終わるときは、それらを無視しない。この変数は、file-name-all-completionsに影響しない。

典型的な値は、以下のようになる:

completion-ignored-extensions
     ⇒ (".o" ".elc" "~" ".dvi")

completion-ignored-extensionsのある要素がスラッシュ‘/’で終わる場合、それはディレクトリーを示す。スラッシュで終わらない要素がディレクトリーにマッチすることは決してない。したがって、上記の値はfoo.elcという名前のディレクトリーを除外しないだろう。

25.9.7 標準的なファイル名

Emacs Lispプログラムが特定の用途のために標準的なファイル名を指定する必要がある場合があります。典型的には、カレントユーザーにより指定された設定データを保持する場合がそうです。そのようなファイルは通常、user-emacs-directoryにより指定されるディレクトリーに置かれ、デフォルトでは~/.emacs.dです(initファイルを参照)。たとえば、abbrev(abbreviation: 省略形)の定義は、デフォルトでは~/.emacs.d/abbrev_defsに格納されます。このようなファイル名を指定するには、関数locate-user-emacs-fileを使用するのが、もっとも簡単な方法です。

Function: locate-user-emacs-file base-name &optional old-name

この関数は、Emacs特有の設定ファイル、またはデータファイルにたいする絶対ファイル名をリターンする。引数base-nameは、ソファイル名であること。リターン値は、user-emacs-directoryで指定されるディレクトリー内の絶対ファイル名である。このディレクトリーが存在しない場合、この関数はディレクトリーを作成する。

オプション引数old-nameが非nilの場合、それはユーザーのホームディレクトリー内のファイル~/old-nameを指定する。そのようなファイルが存在する場合、リターン値はbase-nameで指定されるファイルではなく、そのファイルの絶対ファイル名となる。これは、Emacsパッケージが後方互換を提供するために使用されることを意図した引数である。たとえば、user-emacs-directory導入前、abbrevファイルは~/.abbrev_defsに置かれていた。以下は、abbrev-file-nameの定義である:

(defcustom abbrev-file-name
  (locate-user-emacs-file "abbrev_defs" ".abbrev_defs")
  "Default name of file from which to read abbrevs."
  …
  :type 'file)

ファイル名の標準化のための低レベル関数はconvert-standard-filenameで、これはサブルーチンとしてlocate-user-emacs-fileにより使用される。

Function: convert-standard-filename filename

この関数は、filenameにもとづき、カレントオペレーティングシステムの慣習に適合するファイル名をリターンする。

On GNU and other POSIX-like systems, this simply returns filename. On other operating systems, it may enforce system-specific file name conventions; for example, on MS-DOS this function performs a variety of changes to enforce MS-DOS file name limitations, including converting any leading ‘.’ to ‘_’ and truncating to three characters after the ‘.’.

この関数でGNUおよびUnixシステムの慣習に適合する名前を指定して、それをconvert-standard-filenameに渡すのが推奨される使用方法である。

25.10 ディレクトリーのコンテンツ

ディレクトリーとはファイルの一種で、さまざまな名前のファイルを含んでいます。ディレクトリーは、ファイルシステムの機能です。

Emacsはディレクトリー内のファイル名をLispのリストとして一覧したり、シェルコマンドlsを使用してバッファー内にファイル名を表示することができます。後者の場合、Emacsはオプションで各ファイルに関する情報も表示でき、それはlsコマンドに渡すオプションに依存します。

Function: directory-files directory &optional full-name match-regexp nosort

この関数は、ディレクトリーdirectory内のファイルの名前のリストをリターンする。デフォルトでは、このリストはアルファベット順である。

full-nameが非nilの場合、この関数はファイルの絶対ファイル名をリターンし、それ以外は指定されたディレクトリーにたいする相対ファイル名をリターンする。

match-regexpが非nilの場合、この関数はその正規表現にたいするマッチを含むファイル名だけをリターンし、それ以外のファイル名はリストから除外される。大文字小文字を区別するファイルシステムでは、大文字小文字を区別する正規表現マッチングが行われる。

nosortが非nilの場合、directory-filesはリストをソートしないので、取得するファイル名に特定の順序はない。最大限の可能なスピードを得る必要があり、ファイル処理順を気にしない場合は、この関数を使用する。ユーザーから処理順が可視の場合は、名前をソートすれば、おそらくユーザーはより幸せになるだろう。

(directory-files "~lewis")
     ⇒ ("#foo#" "#foo.el#" "." ".."
         "dired-mods.el" "files.texi"
         "files.texi.~1~")

directoryが読み取り可能なディレクトリー名でない場合は、エラーがシグナルされる。

Function: directory-files-recursively directory regexp &optional include-directories: Return all files under directory whose names match regexp. This function searches the specified directory and its sub-directories, recursively, for files whose basenames (i.e., without the leading directories) match the specified regexp, and returns a list of the absolute file names of the matching files (see section absolute file names). The file names are returned in depth-first order, meaning that files in some sub-directory are returned before the files in its parent directory. In addition, matching files found in each subdirectory are sorted alphabetically by their basenames. By default, directories whose names match regexp are omitted from the list, but if the optional argument include-directories is non-nil, they are included.

Function: directory-files-and-attributes directory &optional full-name match-regexp nosort id-format: これは、どのファイルを報告するか、およびファイル名を報告する方法において、directory-filesと似ている。しかし、この関数はファイル名のリストをリターンするかわりに、各ファイルごとにリスト(filename . attributes)をリターンする。ここでattributesは、そのファイルにたいしてfile-attributesがリターンするであろう値である。オプション引数id-formatは、file-attributesの対応する引数と同じ意味をもつ(Definition of file-attributesを参照)。

Function: file-expand-wildcards pattern &optional full

この関数は、ワイルドカードパッケージpatternを展開して、それにマッチするファイル名のリストをリターンする。

絶対ファイル名としてpatternが記述された場合は、値も絶対ファイル名になる。

patternが相対ファイル名で記述されている場合、それはカレントデフォルトディレクトリーにたいして相対的に解釈される。リターンされるファイル名も、通常はカレントデフォルトディレクトリーにたいする相対ファイル名になる。しかしfullが非nilの場合は、絶対ファイル名がリターンされる。

Function: insert-directory file switches &optional wildcard full-directory-p

この関数は、lsのswitchesに対応するフォーマットで、(カレントバッファー内に)ディレクトリーfileのディレクトリーリストを挿入する。これは、挿入したテキストの後にポイントを残す。switchesにはオプション文字列、または個別のオプションを表す文字列リストを指定できる。

The argument file may be either a directory or a file specification including wildcard characters. If wildcard is non-nil, that means treat file as a file specification with wildcards.

full-directory-pが非nilの場合、ディレクトリーリストにたいしてディレクトリーの完全なコンテンツ表示を要求することを意味する。fileがディレクトリーで、スイッチに‘-d’が含まれないときは、tを指定するべきである(lsへのオプション‘-d’は、ディレクトリーのコンテンツではなく、ファイルとしてディレクトリーを表示するよう指定する)。

ほとんどのシステムでは、この関数は変数insert-directory-programの名前のディレクトリーリスト用プログラムを実行することにより機能する。wildcardが非nilの場合は、ワイルドカード展開するために、shell-file-nameで指定されるシェルの実行も行う。

MS-DOSおよびMS-Windowsシステムは、標準的なUnixプログラムlsを欠くので、この関数はLispコードでlsをエミュレートする。

技術的な詳細としては、switchesにロングオプション‘--dired’が含まれる際にinsert-directoryは、diredのためにこれを特別に扱う。しかし他のオプションと同様、通常は等価なショートオプション‘-D’が単にinsert-directory-programに渡されるだけである。

Variable: insert-directory-program: この変数の値は、関数insert-directory用にディレクトリーリストを生成するプログラムである。この値は、Lispコードでリストを生成するシステムでは無視される。

25.11 ディレクトリーの作成・コピー・削除

Emacs Lispのファイル操作関数のほとんどは、ディレクトリーであるようなファイルに使用されたときはエラーとなります。たとえば、delete-fileでディレクトリーの削除はできません。以下のスペシャルカは、ディレクトリーの作成と削除を行うために存在します。

Command: make-directory dirname &optional parents

このコマンドは、dirnameという名前のディレクトリーを作成する。parentsが非nilの場合(インタラクティブな呼び出しでは、常に非nilとなる)、その親ディレクトリーがまだ存在しなければ、最初にそれを作成することを意味する。

mkdirは、これにたいするエイリアスである。

Command: copy-directory dirname newname &optional keep-time parents copy-contents

This command copies the directory named dirname to newname. If newname is a directory name, dirname will be copied to a subdirectory there. See section ディレクトリーの名前.

これは、常にコピーされるファイルのファイルモードを、対応する元のファイルモードに一致させる。

3つ目の引数keep-timeが非nilの場合は、コピーされるファイルの修正時刻を保持することを意味する。プレフィックス引数を与えると、keep-timeが非nilになる。

4つ目の引数parentsは、親ディレクトリーが存在しない場合に作成するかどうかを指定する。インタラクティブな場合、これはデフォルトで発生する。

The fifth argument copy-contents, if non-nil, means to copy the contents of dirname directly into newname if the latter is a directory name, instead of copying dirname into it as a subdirectory.

Command: delete-directory dirname &optional recursive trash

This command deletes the directory named dirname. The function delete-file does not work for files that are directories; you must use delete-directory for them. If recursive is nil, and the directory contains any files, delete-directory signals an error. If recursive is non-nil, there is no error merely because the directory or its files are deleted by some other process before delete-directory gets to them.

delete-directoryは、親ディレクトリーの階層のシンボリックリンクだけをフォローする。

25.12 特定のファイル名の“Magic”の作成

特定のファイル名にたいして、特別な処理を実装できます。これは、それらの名前のmagic化と呼ばれます。この機能は主に、リモートファイルにたいするアクセスの実装に使用されます(Remote Files in The GNU Emacs Manualを参照)。

magicファイル名を定義するには、名前クラスを定義するための正規表現、およびそれにマッチするファイル名にたいするEmacsファイル操作プリミティブすべてを実装するハンドラーを定義しなければなりません。

変数file-name-handler-alistは各ハンドラーに適用するときを決定する正規表現とともに、ハンドラーのリストを保持します。各要素は、以下の形式をもちます:

(regexp . handler)

ファイルアクセス、およびファイル名変換にたいするすべてのEmacsプリミティブは、file-name-handler-alistにたいして与えられたファイル名をチェックします。そのファイル名がregexpにマッチした場合、そのプリミティブがhandlerを呼び出してファイルを処理します。

handlerの1つ目の引数には、プリミティブの名前をシンボルとして与えます。残りの引数は、そのプリミティブに引数として渡されます(これらの引数の1つ目は、ほとんどの場合はファイル名自体である)。たとえば以下を行い:

(file-exists-p filename)

filenameがハンドラーhandlerをもつ場合、handlerは以下のように呼び出されます:

(funcall handler 'file-exists-p filename)

関数が2つ以上の引数をとる場合、それらはファイル名でなければならず、関数はそれらのファイル名それぞれにたいしてハンドラーをチェックします。たとえば、

(expand-file-name filename dirname)

以下を行った場合は、filenameにたいするハンドラーをチェックした後、dirnameにたいするハンドラーをチェックします。どちらの場合も、handlerは以下のように呼び出されます:

(funcall handler 'expand-file-name filename dirname)

その後、handlerはfilenameとdirnameのどちらを処理するか解決する必要があります。

指定されたファイル名が2つ以上のハンドラーにマッチする場合は、ファイル名内で最後に開始するマッチが優先されます。リモートファイルアクセスのようなジョブにたいするハンドラーに先立ち、解凍のようなジョブにたいするハンドラーが最初に処理されるように、このルールが選択されました。

以下は、magicファイル名ハンドラーが処理する操作です:

access-file, add-name-to-file, byte-compiler-base-file-name,
copy-directory, copy-file, delete-directory, delete-file, diff-latest-backup-file, directory-file-name, directory-files, directory-files-and-attributes, dired-compress-file, dired-uncache,
expand-file-name, file-accessible-directory-p, file-acl, file-attributes, file-directory-p, file-equal-p, file-executable-p, file-exists-p, file-in-directory-p, file-local-copy, file-modes, file-name-all-completions, file-name-as-directory, file-name-case-insensitive-p, file-name-completion, file-name-directory, file-name-nondirectory, file-name-sans-versions, file-newer-than-file-p, file-notify-add-watch, file-notify-rm-watch, file-notify-valid-p, file-ownership-preserved-p, file-readable-p, file-regular-p, file-remote-p, file-selinux-context, file-symlink-p, file-truename, file-writable-p, find-backup-file-name,
get-file-buffer, insert-directory, insert-file-contents,
load, make-auto-save-file-name, make-directory, make-directory-internal, make-nearby-temp-file, make-symbolic-link,
process-file, rename-file, set-file-acl, set-file-modes, set-file-selinux-context, set-file-times, set-visited-file-modtime, shell-command, start-file-process, substitute-in-file-name,
temporary-file-directory, unhandled-file-name-directory, vc-registered, verify-visited-file-modtime,
write-region.

insert-file-contentsにたいするハンドラーは通常、visit引数が非nilの場合は、(set-buffer-modified-p nil)によりそのバッファーの変更フラグをクリアーする必要があります。これには、もしそのバッファーがロックされていたら、ロックを解除する効果もあります。

The handler function must handle all of the above operations, and possibly others to be added in the future. It need not implement all these operations itself—when it has nothing special to do for a certain operation, it can reinvoke the primitive, to handle the operation in the usual way. It should always reinvoke the primitive for an operation it does not recognize. Here’s one way to do this:

(defun my-file-handler (operation &rest args)
  ;; 特別に処理する必要がある、
  ;; 特別な操作を最初にチェックする
  (cond ((eq operation 'insert-file-contents) …)
        ((eq operation 'write-region) …)
        …
        ;; 関知しないその他の操作を処理する
        (t (let ((inhibit-file-name-handlers
                  (cons 'my-file-handler
                        (and (eq inhibit-file-name-operation operation)
                             inhibit-file-name-handlers)))
                 (inhibit-file-name-operation operation))
             (apply operation args)))))

ハンドラー関数が通常のEmacsプリミティブを呼び出す決定をした際は、無限再起を引き起こすような、同一ハンドラーからのプリミティブの再呼び出しを防ぐ必要があります。上記の例では、変数inhibit-file-name-handlersとinhibit-file-name-operationにより、これを行う方法を示しています。上記の例のように、これらを正確に使用するよう、注意してください。複数ハンドラーの正しい振る舞い、およびそれぞれがハンドラーをもつかもしれない2つのファイル名にたいする操作にたいする詳細は、非常に重要です。

Handlers that don’t really do anything special for actual access to the file—such as the ones that implement completion of host names for remote file names—should have a non-nil safe-magic property. For instance, Emacs normally protects directory names it finds in PATH from becoming magic, if they look like magic file names, by prefixing them with ‘/:’. But if the handler that would be used for them has a non-nil safe-magic property, the ‘/:’ is not added.

ファイル名ハンドラーは、普通とは異なる方法でそれを処理(handle)するのが、どの操作(operation)なのかを宣言するために、operationsプロパティをもつことができます。このプロパティが非nil値をもつ場合、それは操作のリストであるべきです。その場合は、それらの操作だけがハンドラーを呼び出すでしょう。これは無駄を省きますが、主な目的はオートロードされるハンドラー関数が実際に処理を行うとき以外はロードされないようにすることです。

通常のプリミティブにたいして、単にすべての操作を延期するのは、機能しません。たとえば、ファイル名ハンドラーがfile-exists-pにたいして適用された場合は、通常のloadコードは正しく機能しないでしょうから、ハンドラー自身でloadを処理しなければなりません。しかし、ハンドラーがfile-exists-pプロパティを使用して、file-exists-pを処理しないことを宣言した場合は、普通とは異なる方法でloadを処理する必要はなくなります。

Variable: inhibit-file-name-handlers: この変数は、特定の操作にたいして現在のところ使用を抑制されているハンドラーのリストを保持する。

Variable: inhibit-file-name-operation: 特定のハンドラーにたいして、現在のところ抑制されている操作。

Function: find-file-name-handler file operation: この関数は、fileというファイル名にたいするハンドラー関数、それが存在しなければnilをリターンする。引数operationは、そのファイルを処理する操作であること。これは、ハンドラー呼び出し時に1つ目の引数として渡すことになる値である。operationがinhibit-file-name-operationと等しい、またはそのハンドラーのoperations内に存在しない場合、この関数はnilをリターンする。

Function: file-local-copy filename

この関数は、ファイルfilenameがまだローカルマシン上にない場合は、それをローカルマシン上の通常の非magicファイルにコピーする。magicファイル名は、それらが他のマシン上のファイルを参照する場合は、file-local-copy操作を処理するべきである。リモートファイルアクセス以外の目的にたいして使用されるmagicファイル名は、file-local-copyを処理するべきではない。その場合、この関数はそのファイルをローカルファイルとして扱うだろう。

filenameがローカルの場合、それがmagicか否かにかかわらず、この関数は何も行わずに、nilをリターンする。それ以外では、ローカルコピーファイルのファイル名をリターンする。

Function: file-remote-p filename &optional identification connected

この関数は、filenameがリモートファイルかどうかをテストする。filenameがローカル(リモートではない)の場合、リターン値はnilである。filenameが正にリモートの場合、リターン値はそのリモートシステムを識別する文字列である。

この識別子文字列は、ホスト名とユーザー名、およびリモートシステムへのアクセスに使用されるメソッドを表す文字列も同様に含めることができる。たとえば、ファイル名/sudo::/some/fileにたいするリモート識別子文字列は、/sudo:root@localhost:となる。

2つの異なるファイルにたいしてfile-remote-pが同じ識別子をリターンした場合は、それらが同じファイルシステム上に格納されていて、互いに配慮しつつアクセス可能であることを意味する。これはたとえば、同時に両方のファイルにアクセスするリモートプロセスを開始することが可能なことを意味する。ファイルハンドラーの実装者は、この方式を保証する必要がある。

identificationは、文字列としてリターンされるべき識別子の一部を指定する。identificationにはmethod、user、hostのシンボルを指定できる。他の値はすべてnilのように扱われ、それは完全な識別子文字列をリターンすることを意味する。上記の例では、リモートのuser識別子文字列は、rootになるだろう。

connectedが非nilの場合、たとえfilenameがリモートであっても、Emacsがそのホストにたいする接続をもたない場合、この関数はnilをリターンする。これは、接続が存在しない際の接続の遅延を回避したいときに有用である。

Function: unhandled-file-name-directory filename

This function returns the name of a directory that is not magic. For a non-magic filename it returns the corresponding directory name (see section ディレクトリーの名前). For a magic filename, it invokes the file name handler, which therefore decides what value to return. If filename is not accessible from a local process, then the file name handler should indicate that by returning nil.

これは、サブプロセスの実行に有用である。すべてのサブプロセスは、自身が属すカレントディレクトリーとして非magicディレクトリーをもたなければならず、この関数はそれを導出するよい手段である。

Function: file-local-name filename: This function returns the local part of file filename. For a remote filename, it returns a file name which could be used directly as argument of a remote process. If filename is local, this function returns the file name.

User Option: remote-file-name-inhibit-cache

リモートファイルの属性は、よりよいパフォーマンスのためにキャッシュすることができる。キャッシュがEmacsの制御外で変更された場合、そのキャッシュ値は無効になり、再読込しなければならない。

この変数がnilにセットされていると、キャッシュ値は決して失効しない。このセッティングは、Emacs以外にリモートファイルを変更するものがないことが確実な場合のみ、慎重に使用すること。これがtにセットされていると、キャッシュ値は決して使用されない。これはもっとも安全な値であるが、パフォーマンスは低下するかもしれない。

折衷的な値としては、これを正の数字にセットする。これは、キャッシュされてからその数字の秒数の間は、キャッシュ値を使用することを意味する。リモートファイルが定期的にチェックされる場合には、この変数を定期的なチェックの間隔より小さい値にletバインドするのは、よい考えかもしれない。たとえば:

(defun display-time-file-nonempty-p (file)
  (let ((remote-file-name-inhibit-cache
         (- display-time-interval 5)))
    (and (file-exists-p file)
         (< 0 (nth 7 (file-attributes
                       (file-chase-links file)))))))

25.13 ファイルのフォーマット変換

Emacsは、バッファー内のデータ(テキスト、テキストプロパティ、あるいはその他の情報)と、ファイル名に格納するのに適した表現との間で双方向の変換をするために、複数のステップを処理します。このセクションでは、このフォーマット変換(format conversion)を行う基本的な関数、すなわちファイルをバッファーに読み込むinsert-file-contentsと、バッファーをファイルに書き込むwrite-regionを説明します。

25.13.1 概要

関数insert-file-contents:

最初に、ファイルからバイトをバッファーに挿入し、
バイトを適切な文字にデコードした後、
format-alistのエントリーにより定義されているようにフォーマット処理して、
after-insert-file-functions内の関数を呼び出す。

関数write-region:

最初に、write-region-annotate-functions内の関数を呼び出し、
format-alistのエントリーにより定義されているようにフォーマット処理して、
文字を適切なバイトにエンコードした後、
そのバイトでファイルを変更する。

これは、もっとも低レベルでの操作を対照的に示したもので、対象の読み取りと書き込みの処理が逆順で対応しています。このセクションの残りでは、上記で名前のでた3つの変数を取り囲む2つの機能と、いくつかの関連する関数を説明します。文字のエンコードとデコードについての詳細は、コーディングシステムを参照してください。

25.13.2 ラウンドトリップ仕様

読み取りと書き込みのもっとも一般的な機能は、変数format-alistで制御されます。これはファイルフォーマット(file format)仕様のリストで、Emacsバッファー内のデータにたいして、ファイル内で使用されるテキスト表現を記述します。読み取りと書き込みの仕様記述はペアーになっており、わたしたちがそれを“ラウンドトリップ(round-trip)”仕様と呼ぶのは、これが理由です(非ペアー仕様については、see section 漸次仕様を参照)。

Variable: format-alist

このリストには、定義されるファイルフォーマットごとに、1つのフォーマット定義が含まれる。フォーマット定義はそれぞれ、以下の形式のリストである:

(name doc-string regexp from-fn to-fn modify mode-fn preserve)

以下は、フォーマット定義内で要素がもつ意味である:

name

フォーマットの名前。

doc-string

フォーマットのドキュメント文字列。

regexp

このフォーマットで表現されるファイルの認識に使用される正規表現。nilの場合、フォーマットが自動的に適用されることは決してない。

from-fn

このフォーマットのデータをデコードする、(ファイルデータを通常のEmacsデータ表現に変換するための)シェルコマンド、または関数。

シェルコマンドは文字列として表され、Emacsはそのコマンドを、変換処理のためのフィルターとして実行する。

from-fnが関数の場合、それは変換するべきバッファー部分を指定する2つの引数、beginとendで呼び出される。これは、インプレースでテキストを編集することにより変換を行うべきである。これはテキスト長を変更する可能性があるので、from-fnは変更されたend位置をリターンすること。

One responsibility of from-fn is to make sure that the beginning of the file no longer matches regexp. Otherwise it is likely to get called again. Also, from-fn must not involve buffers or files other than the one being decoded, otherwise the internal buffer used for formatting might be overwritten.

to-fn

このフォーマットのデータをエンコード、すなわち通常のEmacsデータ表現をこのフォーマットに変換するためのシェルコマンド、または関数。

to-fnが文字列の場合、それはシェルコマンドである。Emacsは変換処理のためのフィルターとして、このコマンドを実行する。

to-fnが関数の場合、それは3つの引数で呼び出される。beginとendは変換されるべきバッファー部分、bufferでそれがどのバッファーかを指定する。変換を行うには、2つの方法がある:

そのバッファー内でインプレースで編集を行う。この場合、to-fnは変更にしたがい、テキスト範囲のend位置をリターンするべきである。
注釈(annotation)のリストをリターンする。これは、(position . string)という形式の要素をもつリストで、positionは書き込まれるテキスト内での相対位置を指定する整数、stringはそこに追加される注釈である。このリストは、to-fnがそれをリターンする際、位置順でソートされていなければならない。
write-regionが実際にバッファーからファイルにテキストを書き込む際には、指定された注釈を対応する位置に混合する。これはすべて、バッファーを変更せずに行われる。

to-fn must not involve buffers or files other than the one being encoded, otherwise the internal buffer used for formatting might be overwritten.

modify

フラグ。エンコード関数がバッファーを変更する場合はt、注釈リストをリターンすることにより機能する場合はnil。

mode-fn

このフォーマットから変換されたファイルをvisit後に呼び出される、マイナーモード関数。この関数は1つの引数で呼び出され、それが整数1の場合、マイナーモード関数はそのモードを有効にする。

preserve

フラグ。format-write-fileがbuffer-file-formatからこのフォーマットを取り除くべきでない場合はt。

関数insert-file-contentsは、指定されたファイルを読み込む際にファイルフォーマットを自動的に認識します。これは、フォーマット定義の正規表現にたいしてファイルの先頭テキストをチェックして、マッチが見つかった場合は、そのフォーマットにたいするデコード関数を呼び出します。その後は再度、既知のフォーマットすべてをチェックします。適用できるフォーマットがない間は、チェックを続行します。

find-file-noselect、またはそれを使用するコマンドでファイルをvisitすることにより、同じように変換が行われます(内部でinsert-file-contentsを呼び出すため)。さらに、それをデコードする各フォーマットのモード関数も呼び出します。これは、バッファーローカル変数buffer-file-format内に、フォーマット名のリストを格納します。

Variable: buffer-file-format: この変数は、visitしているファイルのフォーマットを表す。より正確には、これはカレントバッファーのファイルをvisitに起因するデコードのファイルフォーマット名のリストである。これは、すべてのバッファーにたいして、常にローカルである。

write-regionがデータをファイルに書き込む際には、まずbuffer-file-formatにリストされたフォーマットにたいするエンコード関数を、リスト内での出現順に呼び出します。

Command: format-write-file file format &optional confirm: このコマンドは、カレントバッファーのコンテンツを、フォーマット名のリストformatにもとづいたフォーマットで、ファイルfileに書き込む。これはformatを起点に、buffer-file-formatの値からpreserveフラグ(上記参照)が非nilの要素にたいして、それがまだformat内に存在しない場合は、任意の個数それらを追加する。その後、将来の保存においてデフォルトとなるよう、このフォーマットでbuffer-file-formatを更新する。format引数を除き、このコマンドはwrite-fileと似ている。特に、confirmはwrite-fileでの対応する引数と、意味およびinteractiveでの扱いが同じである。Definition of write-fileを参照のこと。

Command: format-find-file file format

このコマンドは、ファイルfileを探して、それをフォーマットformatにしたがって変換する。これは、後でそのバッファーを保存する場合に、formatをデフォルトにすることも行う。

引数formatは、フォーマット名のリストである。formatがnilの場合、何の変換も行われない。interactiveに呼び出した場合は、formatにたいして単にRETをタイプすると、nilが指定される。

Command: format-insert-file file format &optional beg end

このコマンドは、ファイルfileのコンテンツを、フォーマットformatにしたがって変換して挿入する。begとendが非nilの場合、それはinsert-file-contentsと同様、ファイルのどの部分を読み込むかを指定する(ファイルの読み込みを参照)。

リターン値は、絶対ファイル名のリスト、および挿入されたデータの長さ(変換後)であり、これはinsert-file-contentsがリターンするものと同様である。

Variable: buffer-auto-save-file-format: この変数は、自動保存(auto-saving)にたいして使用するフォーマットを指定する。値はbuffer-file-formatと同様、ファイル名のリストであるが、これはauto-saveファイルへの書き込みで、buffer-file-formatのかわりに使用される。値がt(デフォルト)の場合、自動保存は当バッファーの通常の保存時と同じフォーマットを使用する。この変数は、すべてのバッファーにおいて、常にバッファーローカルである。

25.13.3 漸次仕様

前のサブセクション(ラウンドトリップ仕様を参照)で説明したラウンドトリップ指定とは対照的に、変数after-insert-file-functionsとwrite-region-annotate-functionsを使用して、読み取りと書き込みの変換を個別に制御できます。

変換は、ある表現を起点として、他の表現を生成します。これを行う変換が1つだけのときは、何を起点とするかに関して競合は存在しません。しかし、複数の変換呼び出しが存在する場合、同じデータを起点にする必要がある2つの変換の間に、競合が発生するかもしれません。

この状況を理解するには、write-region中のテキストプロパティの変換コンテキストが最善です。たとえば、あるバッファーの位置42の文字が‘X’で、それのテキストプロパティがfooだとします。fooにたいする変換が、たとえばそのバッファーに‘FOO:’を挿入することにより行われる場合、それは位置42の文字‘X’を‘F’に変更します。そして次の変換は、間違ったデータを起点に開始されるでしょう。

競合を避けるためには、協調的な変換がバッファーを変更せずに、position昇順でソートされた、(position . string)という形式の要素をもつリストを、注釈(annotations)に指定します。

2つ以上の変換が存在する場合、write-regionはそれらの注釈を、1つのソート済みリストに破壊的にマージします。後でそのバッファーのテキストを実際にファイルに書き込む際に、対応する位置にある指定された注釈を混合します。これはすべて、バッファーを変更せずに行われます。

これとは対照的に、読み取り時にはそのテキストの混合された注釈は、即座に処理されます。insert-file-contentsは、変更される何らかのテキストの先頭にポイントをセットしてから、そのテキストの長さで変換関数を呼び出します。これらの関数は常に、挿入されるテキストの先頭のポイントをリターンするべきです。最初の変換により注釈が削除されても、その後の変換が誤って処理することはないので、このアプローチは読み取りに際しては正しく機能します。すべての変換関数は、それが認識する注釈のスキャン、その注釈の削除、バッファーテキストの変更(たとえばテキストプロパティのセット等)、およびそれらの変更に由来する更新されたテキスト長のリターンを行うべきです。１つの関数によりリターンされた値は、次の関数への引数になります。

Variable: write-region-annotate-functions

write-regionにたいして呼び出す、関数のリスト。リスト内の各関数は、書き込まれるリージョンの開始と終了の、2つの引数で呼び出される。これらの関数は、そのバッファーのコンテンツを変更するべきではない。かわりに注釈をリターンすること。

特別なケースとして、関数がカレントと異なるバッファーをリターンするかもしれない。Emacsはこれを、カレントバッファーが出力される変更されたテキストを含むものとして理解する。つまり、Emacsはwrite-region呼び出しの引数startとendを、新たなバッファーのpoint-minとpoint-maxに変更して与える。さらに、以前のすべての注釈はこの関数により処理されるので、Emacsはそれらの破棄も行う。

Variable: write-region-post-annotation-function

この変数の値が非nilの場合、それは関数であること。この関数は、write-region完了後に引数なしで呼び出される。

write-region-annotate-functions内のある関数がカレントと異なるバッファーをリターンした場合、Emacsはwrite-region-post-annotation-functionを複数回呼び出す。Emacsは最後にカレントだったバッファーでそれを呼び出し、その前にカレントだったバッファーで再度これを呼び出す、...のようにして元のバッファーに戻る。

したがって、write-region-annotate-functions内の関数は、バッファーを作成して、kill-bufferのそのバッファーでのローカル値にこの変数を与え、変更されたテキストでそのバッファーをセットアップして、そのバッファーをカレントにすることができる。そのバッファーは、write-region完了後にkillされるだろう。

Variable: after-insert-file-functions: このリスト内の各関数は、挿入されるテキストの先頭にポイントがある状態で、挿入される文字数を１つの引数として、insert-file-contentsにより呼び出される。すべての関数はポイントを未変更のまま、その関数によって変更された、挿入後テキストの新たな文字数をリターンするべきである。

わたしたちは、ユーザーがファイル内にテキストプロパティを格納したりそれらを取得するために、そしてさまざまなデータフォーマットを体験することにより、適切なフォーマットを見つけるために、これらのフックを使用してLispプログラムを記述することを推奨します。最終的には、わたしたちがEmacs内にインストールできる、良質で汎用性のある拡張をユーザーが開発することを望みます。

わたしたちは、テキストプロパティの名前や値として、任意のLispオブジェクトの処理を試みることは推奨しません — なぜなら汎用的なプログラムはおそらく記述が困難で、かつ低速だからです。かわりに、十分な柔軟性をもち、エンコードが難しすぎない、想定されるデータ型のセットを選択してください。

26 バックアップと自動保存

バックアップファイルおよびauto-save(自動保存)ファイルは、Emacsがクラッシュ、またはユーザー自身のエラーからユーザーの保護を試みるための、2つの手段です。自動保存(auto-saving)は、カレントの編集セッション開始以降のテキストを保存します。一方バックアップファイルは、カレントセッションの前のファイルコンテンツを保存します。

26.1 ファイルのバックアップ

バックアップファイル(backup file)とは、編集中ファイルの古いコンテンツのコピーです。Emacsは、visitされているファイルにバッファーを最初に保存するとき、バックアップファイルを作成します。したがって、バックアップファイルには通常、カレント編集セッションの前にあったような、ファイルのコンテンツが含まれています。バックアップファイルのコンテンツには、通常は一度存在したバックアップファイルが変更されずに残ります。

バックアップは通常、visitされているファイルを新たな名前にリネームすることにより作成されます。オプションで、バックアップファイルがvisitされているファイルをコピーすることにより作成されるように指定できます。この選択により、複数の名前をもつファイルのときに、違いが生じます。また、編集中のファイルの所有者が元のオーナーのままか、それとも編集ユーザーになるかにも、影響し得ます。

デフォルトでは、Emacsは編集中のファイルごとに、単一のバックアップファイルを作成します。かわりに、番号付きバックアップ(numbered backup)を要求することもできます。その場合は、新たなバックアップファイルそれぞれが、新たな名前を得ます。必要なくなったときは古い番号付きバックアップを削除したり、Emacsがそれらを自動的に削除することもできます。

For performance, the operating system may not write the backup file’s contents to secondary storage immediately, or may alias the backup data with the original until one or the other is later modified. See section Files and Secondary Storage.

26.1.1 バックアップファイルの作成		Emacsがバックアップファイルを作成する方法とタイミング。
26.1.2 リネームかコピーのどちらでバックアップするか?		2つの選択肢: 古いファイルのリネームとコピー。
26.1.3 番号つきバックアップファイルの作成と削除		ソースファイルごとに複数のバックアップを保持する。
26.1.4 バックアップファイルの命名		バックアップファイル名の計算方法とカスタマイズ。

26.1.1 バックアップファイルの作成

Function: backup-buffer

この関数は、もしそれが適切であれば、カレントバッファーにvisitされているファイルのバックアップを作成する。これは、最初のバッファー保存を行う前に、save-bufferにより呼び出される。

リネームによりバックアップが作成された場合、リターン値は(modes extra-alist backupname)という形式のコンスセルである。ここでmodesは、file-modes(アクセシビリティのテストを参照)でリターンされるような元ファイルのモードビット、extra-alistはfile-extended-attributes(拡張されたファイル属性を参照)によりリターンされるような元ファイルの拡張属性を示すalist、そしてbackupnameはバックアップの名前である。

他のすべての場合(コピーによりバックアップが作成された、またはバックアップが作成されなかった)、この関数はnilをリターンする。

Variable: buffer-backed-up: このバッファーローカル変数は、そのバッファーのファイルがバッファーによりバックアップされたかどうかを明示する。非nilの場合、バックアップファイルは書き込み済みであり、それ以外では、(バックアップが有効なら)次回保存時にファイルはバックアップされる。この変数は永続的にローカルであり、kill-all-local-variablesはそれを変更しない。

User Option: make-backup-files

この変数は、バックアップファイルを作成するかどうかを決定する。非nilの場合、Emacsは初回保存時にすべてのファイルのバックアップを作成する — ただしbackup-inhibitedがnilの場合(以下参照)。

以下の例は、Rmailバッファーだけで変数make-backup-filesを変更して、それ以外では変更しない方法を示す。この変数をnilにセットすると、Emacsはそれらのファイルのバックアップ作成をストップし、それはディスク容量の消費を節約するだろう(あなたは、このコードをinitファイルに配置したいと思うかもしれない)。

(add-hook 'rmail-mode-hook
          (lambda () (setq-local make-backup-files nil)))

Variable: backup-enable-predicate

この変数の値は、あるファイルがバックアップファイルをもつべきかどうかを決定する、特定の機会に呼び出される関数である。関数は、判断すべき絶対ファイル名という、1つの引数を受け取る。この関数がnilをリターンした場合、そのファイルにたいするバックアップは無効になる。それ以外では、このセクション内の他の変数がバックアップ作成の是非と方法を指定する。

デフォルト値はnormal-backup-enable-predicateで、これはtemporary-file-directoryとsmall-temporary-file-directory内のファイルをチェックする。

Variable: backup-inhibited

この変数が非nilの場合、バックアップは抑止される。これは、visitされているファイル名にたいするbackup-enable-predicateのテスト結果を記録する。さらに、visitされているファイルにたいするバックアップ抑止にもとづくその他機構によっても、使用され得る。たとえば、VCはバージョンコントロールシステムに管理されるファイルのバックアップを防ぐために、この変数を非nilにセットする。

これは永続的にローカルなので、メジャーモード変更により値は失われない。メジャーモードはこの変数ではなく、かわりにmake-backup-filesをセットするべきである。

User Option: backup-directory-alist

This variable’s value is an alist of filename patterns and backup directories. Each element looks like

(regexp . directory)

名前がregexpにマッチするファイルのバックアップが、directory内に作成されるだろう。directoryには相対ディレクトリー、または絶対ディレクトリーを指定できる。絶対ディレクトリーの場合は、マッチするすべてのファイルが同じディレクトリー内にバックアップされる。このディレクトリー内でのファイル名は、クラッシュを避けるために、バックアップされるファイルの完全名のすべてのディレクトリー区切りは、‘!’に変更される。結果の名前を切り詰めるファイルシステムでは、これは正しく機能しないだろう。

For the common case of all backups going into one directory, the alist should contain a single element pairing ‘"."’ with the appropriate directory.

この変数がnil(デフォルト)、またはファイル名のマッチに失敗した場合、バックアップは元のファイルのディレクトリーに作成される。

長いファイル名のないMS-DOSファイルシステムでは、この変数は常に無視される。

User Option: make-backup-file-name-function

この変数の値は、バックアップファイル名を作成する関数である。関数make-backup-file-nameは、これを呼び出す。Naming Backup Filesを参照のこと。

特定のファイルにたいして特別なことを行うために、これをバッファーローカルにすることもできる。変更する場合は、backup-file-name-pとfile-name-sans-versionsも変更する必要があるかもしれない。

26.1.2 リネームかコピーのどちらでバックアップするか?

Emacsがバックアップファイルを作成できる、2つの方法があります:

Emacsは元のファイルをリネームすることができ、それがバックアップファイルになる。その後、バッファーの保存は新たなファイルに書き込まれる。この手順後、元ファイルの他のすべての名前(ハードリンク)はバックアップファイルを参照することになる。新たなファイルの所有者は編集を行っているユーザーになり、グループはそのディレクトリー内でそのユーザーが新たなファイルを書き込んだときのデフォルトのグループになる。
Emacsは元のファイルをバックアップファイルにコピーでき、新たな内容はその後、元のファイルに上書きされる。この手順後、元のファイルの他のすべての名前(ハードリンク)は、そのファイルの(更新された)カレントバージョンを参照し続ける。ファイルの所有者とグループは変更されない。

デフォルトは、1つ目の方法のリネームです。

変数backup-by-copyingが非nilの場合、それは2つ目の方法、つまり元のファイルをコピーして、新たなバッファー内容で上書きすることを意味します。変数file-precious-flagが非nilの場合にも、(メイン機能の副作用として)この効果があります。バッファーの保存を参照してください。

User Option: backup-by-copying: この変数が非nilの場合、Emacsは常にコピーによりバックアップファイルを作成する。デフォルトはnil。

以下の3つの変数が非nilの際は、ある特定のケースに2つ目の方法が使用されます。その特定のケースに該当しないファイルの処理に影響はありません。

User Option: backup-by-copying-when-linked

この変数が非nilの場合、Emacsは複数名(ハードリンク)をもつファイルにたいして、コピーによりバックアップを作成する。デフォルトはnil。

backup-by-copyingが非nilの場合は常にコピーによりバックアップが作成されるので、この変数はbackup-by-copyingがnilのときだけ意味がある。

User Option: backup-by-copying-when-mismatch

この変数が非nil(デフォルト)の場合、リネームによりファイルの所有者、またはグループが変更されるケースでは、Emacsはコピーによりバックアップを作成する。

リネームによりファイルの所有者、またはグループが変更されない場合、値は効果をもたない。つまり、そのディレクトリーで新たに作成されるファイルにたいするデフォルトのグループに属するユーザーにより所有されるファイルが該当する。

backup-by-copyingが非nilの場合は常にコピーによりバックアップが作成されるので、この変数はbackup-by-copyingがnilのときだけ意味がある。

User Option: backup-by-copying-when-privileged-mismatch

この変数が非nilの場合、特定のユーザーID値(具体的には、特定の値以下のID数値)にたいしてのみ、backup-by-copying-when-mismatchと同じように振る舞うことを指定する。変数には、その数値をセットする。

したがって、ファイル所有者の変更を防ぐ必要がある際は、backup-by-copying-when-privileged-mismatchを0にセットすれば、スーパーユーザーだけがコピーによるバックアップを行うことができる。

デフォルトは200。

26.1.3 番号つきバックアップファイルの作成と削除

ファイルの名前がfooの場合、番号付きバックアップのバージョン名はfoo.~v~となります。vはfoo.~1~、foo.~2~、foo.~3~、…、foo.~259~のように、さまざまな整数です。

User Option: version-control

この変数は、単一の非番号付きバックアップファイルを作成するか、それとも複数の番号付きバックアップを作成するかを制御する。

nil: visitされたファイルが番号付きバックアップの場合は番号付きバックアップを作成し、それ以外は作成しない。これがデフォルトである。
never: 番号付きバックアップを作成しない。
anything else: 番号付きバックアップを作成する。

番号付きバックアップを使用することにより、バックアップのバージョン番号は最終的には非常に大きな番号になるので、それらを削除しなければなりません。Emacsはこれを自動で行うことができ、ユーザーに削除するか確認することもできます。

User Option: kept-new-versions: この変数の値は、新たな番号付きバックアップが作成された際に保持すべき、もっとも新しいバージョンの個数である。新たに作成されたバックアップもカウントされる。デフォルトは2。

User Option: kept-old-versions: この変数の値は、新たな番号付きバックアップが作成された際に保持すべき、もっとも古いバージョンの個数である。デフォルトは2。

番号が1、2、3、5、7のバックアップがあり、かつこれらの変数が値2をもつ場合は、番号が1と2のバックアップは古いバージョンとして保持され、番号が5と7のバックアップは新しいバージョンとして保持される。そして、番号が3のバックアップは、余分なバックアップとなる。関数find-backup-file-name(バックアップファイルの命名を参照)は、どのバージョンのバックアップを削除するかを決定する役目を負うが、この関数自身がバックアップを削除する訳ではない。

User Option: delete-old-versions: この変数がtの場合は、ファイルの保存により、余分なバージョンのバックアップは、暗黙里に削除される。nilの場合は、余分なバックアップの削除前に確認を求めることを意味し、それ以外では、余分なバックアップは削除されない。

User Option: dired-kept-versions: この変数は、Dired内のコマンド.(ピリオド。dired-clean-directory)で、もっとも新しいバージョンのバックアップをいくつ保持するかを指定する。これは、新たにバックアップファイルを作成する際に、kept-new-versionsを指定するのと同等である。デフォルトは2。

26.1.4 バックアップファイルの命名

このセクションでは、主にバックアップファイルの命名規則を再定義してカスタマイズできる関数を記載します。これらの1つを変更した場合は、おそらく残りも変更する必要があります。

Function: backup-file-name-p filename

この関数は、filenameがバックアップファイルとして利用可能ならば、非nil値をリターンする。これは名前のチェックだけを行い、filenameという名前のファイルが存在するかどうかはチェックしない。

(backup-file-name-p "foo")
     ⇒ nil

(backup-file-name-p "foo~")
     ⇒ 3

この関数の標準的な定義は、以下のようになる:

(defun backup-file-name-p (file)
  "FILEがバックアップファイルなら\
(番号付きか否かに関わらず)非nilをリターンする"
  (string-match "~\\'" file))

このように、ファイル名が‘~’で終わる場合、この関数は非nil値をリターンする(ドキュメント文字列を分割するために、1行目でバックスラッシュを使用しているが、これはドキュメント文字列内で単一行を生成する)。

この単純な式は、カスタマイズのための再定義を簡便にするために、個々の関数内に配されている。

Function: make-backup-file-name filename

この関数は、ファイルfilenameの非番号付きバックアップファイル名として使用される文字列をリターンする。Unixでは、これは単にfilenameにチルダを追加する。

ほとんどのオペレーティングシステムでは、この関数の標準的な定義は以下のようになる:

(defun make-backup-file-name (file)
  "FILEにたいして非番号付きバックアップファイル名を作成する"
  (concat file "~"))

この関数を再定義することにより、バックアップファイルの命名規則を変更できる。以下は、チルダの追加に加えて、先頭に‘.’を追加するよう、make-backup-file-nameを再定義する例である:

(defun make-backup-file-name (filename)
  (expand-file-name
    (concat "." (file-name-nondirectory filename) "~")
    (file-name-directory filename)))

(make-backup-file-name "backups.texi")
     ⇒ ".backups.texi~"

Diredコマンドのいくつかを含むEmacsの一部では、バックアップファイル名が‘~’で終わると仮定している。この規則にしたがわない場合、深刻な問題とはならないだろうが、それらのコマンドが若干好ましくない結果をもたらすかもしれない。

Function: find-backup-file-name filename

この関数は、filenameの新たなバックアップファイル用のファイル名を計算する。これは、特定の既存バックアップファイルにたいする削除の提案も行うかもしれない。find-backup-file-nameは、CARが新たなバックアップファイル名で、CDRが削除を提案するバックアップファイルのリストであるようなリストをリターンする。値にはnilも指定でき、これはバックアップが作成されないことを意味する。

kept-old-versionsおよびkept-new-versionsの2つの変数は、どのバージョンのバックアップを保持するべきかを決定する。この関数は、値のCDRから該当するバージョンを除外することにより、それらを保持する。番号つきバックアップファイルの作成と削除を参照のこと。

In this example, the value says that ~rms/foo.~5~ is the name to use for the new backup file, and ~rms/foo.~3~ is an excess version that the caller should consider deleting now.

(find-backup-file-name "~rms/foo")
     ⇒ ("~rms/foo.~5~" "~rms/foo.~3~")

Function: file-newest-backup filename

この関数は、filenameにたいするもっとも最近のバックアップファイル名、バックアップファイルがない場合はnilをリターンする。

ファイル比較関数のいくつかは、自動的にもっとも最近のバックアップを比較できるように、この関数を使用している。

26.2 自動保存

Emacsは、visitしているすべてのファイルを定期的に保存します。これは自動保存(auto-saving)と呼ばれます。自動保存は、システムがクラッシュした場合に失われる作業量を、ある作業量以下にします。デフォルトでは、自動保存は300キーストロークごと、またはidle時の30秒後に発生します。自動保存に関するユーザー向けの情報については、Auto-Saving: Protection Against Disasters in The GNU Emacs Manualを参照してください。ここでは、自動保存の実施に使用される関数と、それらを制御する変数について説明します。

Variable: buffer-auto-save-file-name

このバッファーローカル変数は、カレントバッファーの自動保存に使用されるファイル名である。そのバッファーが自動保存されるべきでない場合は、nil。

buffer-auto-save-file-name
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"

Command: auto-save-mode arg

これはバッファーローカルなマイナーモードであるAuto Saveモードにたいする、モードコマンドである。Auto Saveモードが有効なときは、そのバッファーで自動保存が有効である。呼び出し方は、他のマイナーモードと同様(マイナーモード記述の規約を参照)。

ほとんどのマイナーモードとは異なり、auto-save-mode変数は存在しない。buffer-auto-save-file-nameが非nil、かつbuffer-saved-size(以下参照)が非0ならば、Auto Saveモードは有効である。

Function: auto-save-file-name-p filename

この関数は、filenameがauto-saveファイルのような文字列の場合は、非nilをリターンする。先頭と末尾がハッシュマーク(‘#’)の名前はauto-saveファイルの可能性があるという、auto-saveファイルにたいする通常の命名規則を想定する。引数filenameは、ディレクトリーパートを含むべきではない。

(make-auto-save-file-name)
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"

(auto-save-file-name-p "#backups.texi#")
     ⇒ 0

(auto-save-file-name-p "backups.texi")
     ⇒ nil

この関数の標準的な定義は、以下のようになる:

(defun auto-save-file-name-p (filename)
  "FILENAMEが以下を満たすなら非nilをリターンする"
  (string-match "^#.*#$" filename))

auto-saveファイルの命名規則規則を変更したいときにカスタマイズできるようにするために、この関数は存在する。これを再定義した場合は、それに対応して関数make-auto-save-file-nameも忘れずに再定義すること。

Function: make-auto-save-file-name

この関数は、カレントバッファーの自動保存に使用されるファイル名をリターンする。これは、ファイル名の先頭と末尾にハッシュマーク(‘#’)を単に追加する。この関数は、変数auto-save-visited-file-name(以下参照)を調べない。呼び出し側は、まずその変数をチェックするべきである。

(make-auto-save-file-name)
     ⇒ "/xcssun/users/rms/lewis/#backups.texi#"

以下は、この関数の標準的な定義の簡略版である:

(defun make-auto-save-file-name ()
  "カレントバッファーの自動保存に使用される\
ファイル名をリターンする"
  (if buffer-file-name

      (concat
       (file-name-directory buffer-file-name)
       "#"
       (file-name-nondirectory buffer-file-name)
       "#")
    (expand-file-name
     (concat "#%" (buffer-name) "#"))))

auto-saveファイルの命名規則をカスタマイズするために再定義できるように、これは独立した関数として存在している。ただし、これに対応した方法でauto-save-file-name-pも忘れずに変更すること。

User Option: auto-save-visited-file-name

この変数が非nilの場合、Emacsはvisit中のファイルにバッファーを自動保存する。つまり、自動保存は編集中ファイルと同じファイルにたいして行われる。通常この変数はnilなので、auto-saveファイルはmake-auto-save-file-nameで作成された別の名前をもつ。

この変数の値を変更した際は、バッファー内でauto-saveモードが再度有効になるまで、既存バッファーにたいして新たな値は効果をもたない。すでにauto-saveモードが有効な場合は、再度auto-save-modeが呼び出されるまで、同じファイルに自動保存が行われる。

Note that setting this variable to a non-nil value does not change the fact that auto-saving is different from saving the buffer; e.g., the hooks described in バッファーの保存 are not run when a buffer is auto-saved.

Function: recent-auto-save-p: この関数は、カレントバッファーが最後に読み込み、または保存されて以降、自動保存されていればtをリターンする。

Function: set-buffer-auto-saved: この関数は、カレントバッファーを自動保存済みとマークする。そのバッファーは、バッファーテキストが再度変更されるまで、自動保存されないだろう。この関数はnilをリターンする。

User Option: auto-save-interval: この変数の値は、自動保存の頻度を入力イベント数で指定する。この分の入力イベント読み取りごとに、Emacsは自動保存が有効なすべてのバッファーにたいして、自動保存を行う。これを0にすると、タイプした文字数にもとづく自動保存は無効になる。

User Option: auto-save-timeout

この変数の値は、自動保存が発生すべきidle時間の秒数である。この秒数分ユーザーが休止するたびに、Emacsは自動保存が有効なすべてのバッファーにたいして、自動保存を行う(カレントバッファーが非常に大きい場合、指定されたタイムアウトはサイズ増加とともに増加される因子で乗ぜられる。1MBのバッファーにたいして、この因子はおよそ4である)。

値が0、またはnilの場合、idle時間にもとづく自動保存は行われず、auto-save-intervalで指定される入力イベント数の後のみ自動保存が行われる。

Variable: auto-save-hook: このノーマルフックは、自動保存が行われようとするたびに毎回実行される。

User Option: auto-save-default: この変数が非nilの場合は、ファイルをvisitするバッファーの自動保存がデフォルトで有効になり、それ以外では有効にならない。

Command: do-auto-save &optional no-message current-only

この関数は、自動保存される必要があるすべてのバッファーを自動保存する。これは自動保存が有効、かつ前回の自動保存以降に変更されたすべてのバッファーを保存する。

いずれかのバッファーが自動保存される場合、通常do-auto-saveは自動保存が行われる間、それを示すメッセージ‘Auto-saving...’をエコーエリアに表示する。しかし、no-messageが非nilの場合、このメッセージは抑制される。

current-onlyが非nilの場合は、カレントバッファーだけが自動保存される。

Function: delete-auto-save-file-if-necessary &optional force

この関数は、delete-auto-save-filesが非nilなら、カレントバッファーのauto-saveファイルを削除する。これは、バッファー保存時に毎回呼び出される。

forceがnilの場合、この関数は最後に本当の保存が行われて以降、カレントEmacsセッションにより書き込まれたファイルだけを削除する。

User Option: delete-auto-save-files: この変数は、関数delete-auto-save-file-if-necessaryにより使用される。これが非nilの場合、Emacsは(visitされているファイルに)本当に保存が行われたとき、auto-saveファイルを削除する。これはデスク容量を節約し、ディレクトリーを整理する。

Function: rename-auto-save-file: この関数は、visitされているファイルの名前が変更されていれば、カレントバッファーのauto-saveファイルの名前を調整する。これは、カレントEmacsセッションでauto-saveファイルが作成されていれば、既存のauto-saveファイルもリネームする。visitされているファイルの名前が変更されていない場合、この関数は何も行わない。

Variable: buffer-saved-size

このバッファーローカル変数の値は、カレントバッファーが最後に読み取り、保存、または自動保存されたときのバッファーの長さである。これは、サイズの大幅な減少の検知に使用され、それに応じて自動保存がオフに切り替えられる。

-1の場合、それはサイズの大幅な減少により、そのバッファーの自動保存が一時的に停止されていることを意味する。明示的な保存により、この変数に正の値が格納され、自動保存が再び有効になる。自動保存をオフやオンに切り替えることでも、またはこの変数を更新されるので、サイズの大幅な減少は忘れられてしまう。

-2の場合は、そのバッファーがバッファーサイズの変更を無視すべきことを意味する。特に、バッファーサイズの変更により、一時的に自動保存を停止するべきではない。

Variable: auto-save-list-file-name

この変数は、(非nilの場合は)すべてのauto-saveファイルの名前を記録するファイルを指定する。Emacsが自動保存を行うたびに、そのEmacsは自動保存が有効な各バッファーごとに2行ずつ書き込みを行う。1行目はvisitされているファイルの名前(ファイルをvisitしないバッファーの場合は空)、2行目はauto-saveファイルの名前を示す。

Emacsを正常にexitしたときは、このファイルは削除される。Emacsがクラッシュした場合は、このファイルを調べることにより、失われるはずだった作業を含む、すべてのauto-saveファイルを探すことができる。recover-sessionコマンドは、それらを見つけるために、このファイルを使用する。

このファイルにたいするデフォルト名は、ユーザーのホームディレクトリーの、‘.saves-’で始まるファイルを指定する。この名前には、EmacsのプロセスIDと、ホスト名も含まれる。

User Option: auto-save-list-file-prefix: initファイルを読み込んだ後、(nilにセット済みでなければ)Emacsはこのプレフィックスにもとづきホスト名とプロセスIDを追加して、auto-save-list-file-nameを初期化する。initファイル内でこれをnilにセットした場合、Emacsはauto-save-list-file-nameを初期化しない。

26.3 リバート

あるファイルにたいして大きな変更を行った後、気が変わって元に戻したくなった場合は、revert-bufferコマンドでそのファイルの以前のバージョンを読み込むことにより、それらの変更を取り消すことができます。詳細は、Reverting a Buffer in The GNU Emacs Manualを参照してください。

Command: revert-buffer &optional ignore-auto noconfirm preserve-modes

このコマンドは、バージョンのテキストを、ディスク上のvisitされているファイルのテキストで置き換える。これにより、ファイルがvisit、または保存された以降に行ったすべての変更は、アンドゥ(undo: 取り消し)される。

デフォルトでは、もっとも最近のauto-saveファイルのほうがvisitされているファイルより新しく、かつ引数ignore-autoがnilの場合、revert-bufferはユーザーにたいしてかわりにauto-saveファイルを使用するかどうか確認を求める。このコマンドをinteractiveに呼び出したとき、プレフィックス数引数が指定されていなければ、ignore-autoはtとなる。つまり、interactive呼び出しは、デフォルトではauto-saveファイルのチェックを行わない。

revert-bufferは通常、バッファーを変更する前に確認を求める。しかし、引数noconfirmが非nilの場合、revert-bufferは確認を求めない。

このコマンドは通常、normal-modeを使用することにより、そのバッファーのメジャーモードとマイナーモードを再初期化する。しかし、preserve-modesが非nilの場合、モードは変更されずに残る。

リバート(revert: 戻す、復元する)は、insert-file-contentsの置き換え機能を使用することにより、バッファー内のマーカー位置の保持を試みる。バッファーのコンテンツとファイルのコンテンツがリバート操作を行う前に等しい場合、リバートはすべてのマーカーを保持する。等しくない場合、リバートによりバッファーは変更される。この場合は、(もしあれば)バッファーの最初と最後にある未変更のテキスト内にあるマーカーは保持される。他のマーカーを保持しても、それらは正しくないだろう。

Variable: revert-buffer-in-progress-p: revert-bufferは処理を行っている間、この変数を非nil値にバインドする。

このセクションの残りの部分で説明する変数をセットすることにより、revert-bufferが処理を行う方法をカスタマイズできます。

User Option: revert-without-query: この変数は、問い合わせなしでリバートされるべきファイルのリストを保持する。値は、正規表現のリスト。visitされているファイルの名前がこれらの正規表現のいずれかにマッチし、かつバッファーが未変更だがディスク上のファイルは変更されている場合、revert-bufferはユーザーに確認を求めることなく、ファイルをリバートする。

メジャーモードのいくつかは、以下の変数をローカルにバインドすることにより、revert-bufferをカスタマイズします:

Variable: revert-buffer-function

この変数の値は、そのバッファーをリバートするために使用する関数である。これはリバート処理を行うための、2つのオプション引数をとる関数であること。2つのオプション引数ignore-autoとnoconfirmは、revert-bufferが受け取る引数である。

Diredモードのような、編集されるテキストにファイルのコンテンツは含まれず、他の方式により再生成され得るモードは、この変数のバッファーローカル値に、コンテンツを再生成する特別な関数を与えることができる。

Variable: revert-buffer-insert-file-contents-function

この変数の値は、そのバッファーをリバートする際に、更新されたコンテンツの挿入に使用される関数を指定する。その関数は、2つの引数をとる。1つ目は使用するファイル名で、2つ目がtならユーザーはauto-saveファイルの読み込みにたいして確認を求められる。

revert-buffer-functionのかわりにこの変数をモードが変更する理由は、revert-bufferが行残りの処理(ユーザーへの確認、アンドゥリストのクリアー、適切なメジャーモードの決定、以下のフックの実行)にたいする重複や置き換えを避けるためである。

Variable: before-revert-hook: このノーマルフックは、変更されたコンテンツを挿入する前に、デフォルトのrevert-buffer-functionにより実行される。カスタマイズしたrevert-buffer-functionは、このフックを実行するかどうか判らない。

Variable: after-revert-hook: このノーマルフックは、変更されたコンテンツを挿入した後に、デフォルトのrevert-buffer-functionにより実行される。カスタマイズしたrevert-buffer-functionは、このフックを実行するかどうか判らない。

Emacs can revert buffers automatically. It does that by default for buffers visiting files. The following describes how to add support for auto-reverting new types of buffers.

First, such buffers must have a suitable revert-buffer-function and buffer-stale-function defined.

Variable: buffer-stale-function

The value of this variable specifies a function to call to check whether a buffer needs reverting. The default value only handles buffers that are visiting files, by checking their modification time. Buffers that are not visiting files require a custom function of one optional argument noconfirm. The function should return non-nil if the buffer should be reverted. The buffer is current when this function is called.

While this function is mainly intended for use in auto-reverting, it could be used for other purposes as well. For instance, if auto-reverting is not enabled, it could be used to warn the user that the buffer needs reverting. The idea behind the noconfirm argument is that it should be t if the buffer is going to be reverted without asking the user and nil if the function is just going to be used to warn the user that the buffer is out of date. In particular, for use in auto-reverting, noconfirm is t. If the function is only going to be used for auto-reverting, you can ignore the noconfirm argument.

If you just want to automatically auto-revert every auto-revert-interval seconds (like the Buffer Menu), use:

(setq-local buffer-stale-function
     #'(lambda (&optional noconfirm) 'fast))

in the buffer’s mode function.

The special return value ‘fast’ tells the caller that the need for reverting was not checked, but that reverting the buffer is fast. It also tells Auto Revert not to print any revert messages, even if auto-revert-verbose is non-nil. This is important, as getting revert messages every auto-revert-interval seconds can be very annoying. The information provided by this return value could also be useful if the function is consulted for purposes other than auto-reverting.

Once the buffer has a suitable revert-buffer-function and buffer-stale-function, several problems usually remain.

The buffer will only auto-revert if it is marked unmodified. Hence, you will have to make sure that various functions mark the buffer modified if and only if either the buffer contains information that might be lost by reverting, or there is reason to believe that the user might be inconvenienced by auto-reverting, because he is actively working on the buffer. The user can always override this by manually adjusting the modified status of the buffer. To support this, calling the revert-buffer-function on a buffer that is marked unmodified should always keep the buffer marked unmodified.

It is important to assure that point does not continuously jump around as a consequence of auto-reverting. Of course, moving point might be inevitable if the buffer radically changes.

You should make sure that the revert-buffer-function does not print messages that unnecessarily duplicate Auto Revert’s own messages, displayed if auto-revert-verbose is t, and effectively override a nil value for auto-revert-verbose. Hence, adapting a mode for auto-reverting often involves getting rid of such messages. This is especially important for buffers that automatically revert every auto-revert-interval seconds.

If the new auto-reverting is part of Emacs, you should mention it in the documentation string of global-auto-revert-non-file-buffers.

Similarly, you should document the additions in the Emacs manual.

27 バッファー

バッファー(buffer)とは、編集されるテキストを含むLispオブジェクトのことです。バッファーは、visitされるファイルのコンテンツを保持するために使用されます。しかし、ファイルをvisitしないバッファーも存在するかもしれません。一度に複数のバッファーが存在するかもしれませんが、カレントバッファー(current buffer)に指定できるのは、常に1つのバッファーだけです。ほとんどの編集コマンドは、カレントバッファーのコンテンツにたいして作用します。カレントバッファーを含むすべてのバッファーは、任意のウィンドウ内に表示されるときも、表示されない場合もあります。

27.1 バッファーの基礎		バッファーとは?
27.2 カレントバッファー		バッファーをカレントに指定することにより、プリミティブはバッファーのコンテンツにアクセスする。
27.3 バッファーの名前		バッファー名にたいするアクセスと変更。
27.4 バッファーのファイル名		バッファーファイル名は、どのファイルをvisitしているかを示す。
27.5 バッファーの変更		保存が必要なら、バッファーは変更されている(modified)。
27.6 バッファーの変更 Time		Determining whether the visited file was changed behind Emacs’s back.
27.7 読み取り専用のバッファー		読み取り専用バッファーでのテキスト変更は許されない。
27.8 バッファーリスト		すべての既存バッファーを閲覧する方法。
27.9 バッファーの作成		バッファーを作成する関数。
27.10 バッファーのkill		明示的にkillされるまで、バッファーは存在する。
27.11 インダイレクトバッファー		インダイレクトバッファーは、他のバッファーとテキストを共有する。
27.12 2つのバッファー間でのテキストの交換
27.13 バッファーのギャップ		バッファー内のギャップ。

27.1 バッファーの基礎

バッファー(buffer)とは、編集されるテキストを含むLispオブジェクトのことです。バッファーは、visitされるファイルのコンテンツを保持するために使用されます。しかし、ファイルをvisitしないバッファーも存在します。一度に複数のバッファーが存在するかもしれませんが、カレントバッファー(current buffer)に指定できるのは、常に1つのバッファーだけです。ほとんどの編集コマンドは、カレントバッファーのコンテンツにたいして作用します。カレントバッファーを含むすべてのバッファーは、任意のウィンドウ内に表示されるときも、表示されない場合もあります。

Emacs編集におけるバッファーは、個別に名前をもち、編集可能なテキストを保持するオブジェクトです。Lispプログラムにたいして、バッファーはスペシャルデータ型として表されます。バッファーのコンテンツを、拡張可能な文字列と考えることができます。挿入と削除は、バッファー内の任意の箇所で発生し得ます。テキストを参照してください。

Lispのバッファーオブジェクトは、多くの情報要素を含んでいます。これらの情報のいくつかは変数を通じてプログラマーが直接アクセスできるのにたいして、その他の情報は特殊な目的のための関数を通じてのみアクセスすることができます。たとえば、visitされているファイルの名前は変数を通じて直接アクセスできますが、ポイント値はプリミティブ関数からのみアクセスできます。

直接アクセス可能な、バッファー固有の情報は、バッファーローカル(buffer-local)な変数バインディング内に格納されます。これは、特定のバッファー内だけで効力のある変数値のことです。この機能により、それぞれのバッファーは、特定の変数の値をオーバーライドすることができます。ほとんどのメジャーモードは、この方法でfill-columnやcomment-columnのような変数をオーバーライドしています。バッファーローカルな変数、およびそれらに関連する関数についての詳細は、バッファーローカル変数を参照してください。

バッファーからファイルをvisitする関数および変数については、ファイルのvisit、およびバッファーの保存を参照してください。ウィンドウ内へのバッファー表示に関連する関数および変数については、バッファーとウィンドウを参照してください。

Function: bufferp object: この関数は、objectがバッファーならt、それ以外はnilをリターンする。

27.2 カレントバッファー

一般的に、1つのEmacsセッション内には、多くのバッファーが存在します。常に、それらのうちの1つがカレントバッファー(current buffer)に指定され、ます。カレントバッファーとは、ほとんどの編集が行われるバッファーのことです。テキストを調べたり変更するプリミティブのほとんどは、暗黙的にカレントバッファーにたいして処理を行います(テキストを参照)。

通常は、選択されたウィンドウ内に表示されるバッファーがカレントバッファーですが、常にそうではありません。Lispプログラムは、バッファーのコンテンツを処理するために、スクリーン上に表示されているものを変更することなく、任意のバッファーを一時的にカレントに指定できます。カレントバッファーの指定にたいしてもっとも基本的な関数は、set-bufferです。

Function: current-buffer

この関数は、カレントバッファーをリターンする関数。

(current-buffer)
     ⇒ #<buffer buffers.texi>

Function: set-buffer buffer-or-name

この関数は、buffer-or-nameをカレントバッファーにする。buffer-or-nameは既存のバッファー、または既存のバッファーの名前でなければならない。リターン値は、カレントになったバッファーである。

この関数は、そのバッファーをどのウィンドウにも表示しないので、必然的にユーザーはそのバッファーを見ることはできない。しかし、Lispプログラムはその後、そのバッファーにたいして処理を行うことになるだろう。

編集コマンドがエディターコマンドループにリターンする際、Emacsは選択されたウィンドウ内に表示されているバッファーにたいして、自動的にset-bufferを呼び出します。これは混乱を防ぐためで、これにより、Emacsがコマンドを読み取るときに、カーソルのあるバッファーが、コマンドを適用されるバッファーになるのが保証されます(コマンドループを参照)。したがって、異なるバッファーを指示して切り替える場合に、set-bufferを使用するべきではありません。これを行うためには、ウィンドウ内のバッファーへの切り替えで説明されているカを使用してください。

Lisp関数を記述する際は、処理後にカレントバッファーをリストアするために、コマンドループのこの振る舞いに依存しないでください。編集コマンドは、コマンドループだけではなく、他のプログラムからLisp関数としても呼び出されます。呼び出し側にとっては、そのサブルーチンがカレントだったバッファーを変更しないほうが便利です(もちろん、それがサブルーチンの目的でない場合ですが)。

他のバッファーにたいして一時的に処理を行うには、save-current-bufferフォーム内にset-bufferを置きます。以下の例は、コマンドappend-to-bufferの簡略版です:

(defun append-to-buffer (buffer start end)
  "リージョンのテキストをBUFFERに追加する"
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (save-current-buffer
      (set-buffer (get-buffer-create buffer))
      (insert-buffer-substring oldbuf start end))))

ここでは、カレントバッファーを記録するためにローカル変数にバインドしてから、後でsave-current-bufferがそれを再びカレントにするよう、取り計らっています。次に、set-bufferが指定されたバッファーをカレントにして、insert-buffer-substringが元のバッファーの文字列を、指定された(今はカレントの)バッファーにコピーします。

かわりに、with-current-bufferマクロを使用することもできます:

(defun append-to-buffer (buffer start end)
  "BUFFERにリージョンのテキストを追加する"
  (interactive "BAppend to buffer: \nr")
  (let ((oldbuf (current-buffer)))
    (with-current-buffer (get-buffer-create buffer)
      (insert-buffer-substring oldbuf start end))))

どちらの場合でも、追加されるバッファーが偶然他のウィンドウに表示されていた場合には、次回の再表示でそのテキストがどのように変更されたか表示されるでしょう。どのウィンドウにも表示されていない場合には、スクリーン上で即座に変更を目にすることはありません。コマンドはバッファーを一時的にカレントにしますが、そのことがバッファーの表示を誘因する訳ではありません。

バッファーローカルバインディングをもつ変数にたいして、(letや関数引数などで)ローカルバインディングを作成する場合は、そのローカルバインディングのスコープの最初と最後で、同じバッファーがカレントとなることを確認してください。そうしないと、あるバッファーではバインドして、他のバッファーではバインドされないことになるかもしれません!

set-bufferの使用において、カレントバッファーが戻ることに依存しないでください。なぜなら、間違ったバッファーがカレントのときにquitが発生した場合、その処理は行われないでしょう。たとえば上記の例に倣うと、以下は間違ったやり方です:

  (let ((oldbuf (current-buffer)))
    (set-buffer (get-buffer-create buffer))
    (insert-buffer-substring oldbuf start end)
    (set-buffer oldbuf))

例で示したようにsave-current-buffer、またはwith-current-bufferを使用すれば、quitやthrowを、通常の評価と同様に処理できます。

Special Form: save-current-buffer body…

スペシャルフォームsave-current-bufferは、カレントバッファーの識別を保存して、bodyフォームを評価し、最後にそのバッファーをカレントにリストアする。リターン値は、body内の最後のフォームの値である。throwやエラーを通じた異常exitの場合でも、カレントバッファーはリストアされる(非ローカル脱出を参照)。

カレントとして使用されていたバッファーが、save-current-bufferによるexit時にkillされていた場合は、それが再びカレントとなることは当然ない。かわりに、exit直前にカレントバッファーが何であれ、それがカレントになる。

Macro: with-current-buffer buffer-or-name body…

with-current-bufferマクロは、カレントバッファーの識別を保存して、buffer-or-nameをカレントにし、bodyフォームを評価して、最後にカレントバッファーをリストアする。buffer-or-nameには既存のバッファー、または既存のバッファー名を指定しなければならない。

リターン値は、body内の最後のフォームの値である。throwやエラーを通じた異常exitの場合でも、カレントバッファーはリストアされる(非ローカル脱出を参照)。

Macro: with-temp-buffer body…

with-temp-bufferマクロは、一時的なバッファーをカレントバッファーとして、bodyフォームを評価する。これはカレントバッファーの識別を保存して、一時的なバッファーを作成、それをカレントとして、bodyフォームを評価し、一時バッファーをkillする間に、以前のカレントバッファーをリストアする。デフォルトでは、このマクロにより作成されたバッファー内のアンドゥ情報(アンドゥを参照)は記録されない(が、必要ならbodyでそれを有効にできる)。

リターン値は、body内の最後のフォームの値である。最後のフォームとして(buffer-string)を使用することにより、一時バッファーのコンテンツをリターンできる。

throwやエラーを通じた異常exitの場合でも、カレントバッファーはリストアされる(非ローカル脱出を参照)。

Writing to Filesのwith-temp-fileも参照されたい。

27.3 バッファーの名前

それぞれのバッファーは、文字列で表される一意な名前をもちます。バッファーにたいして機能する関数の多くは、引数としてバッファーとバッファー名の両方を受け入れます。buffer-or-nameという名前の引数がこのタイプで、それが文字列でもバッファーでもない場合は、エラーがシグナルされます。bufferという名前の引数は、名前ではなく実際のバッファーオブジェクトでなければなりません。

短命でユーザーが関心をもたないようなバッファーは名前がスペースで始まり、それらについてはlist-buffersおよびbuffer-menuコマンドは無視します(が、ファイルをvisitしているようなバッファーは無視されない)。スペースで始まる名前は、初期状態ではアンドゥ情報の記録も無効になっています。アンドゥを参照してください。

Function: buffer-name &optional buffer

この関数は、bufferの名前を文字列としてリターンする。bufferのデフォルトは、カレントバッファーである。

buffer-nameがnilをリターンした場合、それはbufferがkillされていることを意味する。バッファーのkillを参照のこと。

(buffer-name)
     ⇒ "buffers.texi"

(setq foo (get-buffer "temp"))
     ⇒ #<buffer temp>

(kill-buffer foo)
     ⇒ nil

(buffer-name foo)
     ⇒ nil

foo
     ⇒ #<killed buffer>

Command: rename-buffer newname &optional unique

この関数は、カレントバッファーをnewnameにリネームする。newnameが文字列でない場合は、エラーをシグナルする。

newnameがすでに使用済みの場合、rename-bufferは通常はエラーをシグナルする。しかし、uniqueが非nilの場合は、未使用の名前となるようにnewnameを変更する。interactiveに呼び出した場合は、プレフィックス数引数によりuniqueに非nilを指定できる(この方法により、コマンドrename-uniquelyは実装される)。

この関数は、実際にバッファーに与えられた名前をリターンする。

Function: get-buffer buffer-or-name

この関数は、buffer-or-nameで指定されたバッファーをリターンする。buffer-or-nameが文字列で、かつそのような名前のバッファーが存在しない場合、値はnilになる。buffer-or-nameがバッファーの場合は、与えられたバッファーをリターンする。これは有用とは言い難く、引数は通常は名前である。たとえば:

(setq b (get-buffer "lewis"))
     ⇒ #<buffer lewis>

(get-buffer b)
     ⇒ #<buffer lewis>

(get-buffer "Frazzle-nots")
     ⇒ nil

バッファーの作成の関数get-buffer-createも参照のこと。

Function: generate-new-buffer-name starting-name &optional ignore

この関数は、新たなバッファーにたいして一意となるような名前をリターンする — が、バッファーは作成しない。この名前はstarting-nameで始まり、内部が数字であるような‘<…>’を追加することにより、すべてのバッファーでカレントで使用されていない名前を生成する。この数字は2で始まり、既存バッファーの名前でない名前になる数字まで増加される。

オプション引数ignoreが非nilの場合、それは潜在的にバッファー名であるような文字列であること。これは、たとえそれが(通常は拒絶されるであろう)既存バッファーの名前であっても、試みられた場合は、潜在的に受容可能なバッファーとして考慮することを意味する。つまり‘foo’、‘foo<2>’、‘foo<3>’、‘foo<4>’という名前のバッファーが存在する場合、

(generate-new-buffer-name "foo")
     ⇒ "foo<5>"
(generate-new-buffer-name "foo" "foo<3>")
     ⇒ "foo<3>"
(generate-new-buffer-name "foo" "foo<6>")
     ⇒ "foo<5>"

バッファーの作成の関連する関数generate-new-bufferも参照のこと。

27.4 バッファーのファイル名

バッファーファイル名(buffer file name)とは、そのバッファーにvisitされているファイルの名前です。バッファーがファイルをvisiblyしていなければ、バッファーファイル名はnilです。大抵、バッファー名はバッファーファイル名の非ディレクトリーパートと同じですが、バッファーファイル名とバッファー名は別物であり、個別にセットすることができます。ファイルのvisitを参照してください。

Function: buffer-file-name &optional buffer

この関数は、bufferがvisitしているファイルの、絶対ファイル名をリターンする。bufferがファイルをvisitしていない場合、buffer-file-nameはnilをリターンする。bufferが与えられない場合のデフォルトは、カレントバッファーになる。

(buffer-file-name (other-buffer))
     ⇒ "/usr/user/lewis/manual/files.texi"

Variable: buffer-file-name

このバッファーローカル変数は、カレントバッファーにvisitされているファイルの名前、ファイルをvisitしていなければnilが含まれる。これは永続的なローカル変数であり、kill-all-local-variablesの影響を受けない。

buffer-file-name
     ⇒ "/usr/user/lewis/manual/buffers.texi"

他のさまざまな事項を変更せずに、この変数を変更するのは危険である。通常は、set-visited-file-nameを使用するほうがよい(以下参照)。バッファー名の変更などのような、そこで行われることのいくつかは、絶対必要という訳ではないが、その他の事項はEmacsが混乱するのを防ぐために必要不可欠である。

Variable: buffer-file-truename: このバッファーローカル変数は、カレントバッファーにvisitされているファイルの省略された形式の実名(truename)、ファイルをvisitしていない場合はnilを保持する。これは永続的にローカルであり、kill-all-local-variablesの影響を受けない。See section 本当の名前、およびabbreviate-file-nameを参照のこと。

Variable: buffer-file-number

このバッファーローカル変数は、カレントバッファーにvisitされているファイルのファイル番号(file number)とデバイス番号(device number)、ファイルをvisitしていない場合はnilを保持する。これは永続的にローカルであり、kill-all-local-variablesの影響を受けない。

値は通常、(filenum devnum)のような形式のリストである。この番号ペアーは、システム上でアクセス可能なすべてのファイルの中から、ファイルを一意に識別する。より詳細な情報は、ファイルの属性のfile-attributesを参照のこと。

buffer-file-nameがシンボリックリンク名の場合は、どちらの番号も再帰的なターゲットを参照する。

Function: get-file-buffer filename

この関数は、ファイルfilenameをvisitしているバッファーをリターンする。そのようなバッファーが存在しない場合は、nilをリターンする。引数filenameは文字列でなければならず、展開(ファイル名を展開する関数を参照)された後、killされていないすべてのバッファーがvisitしているファイル名と比較される。バッファーのbuffer-file-nameは、filenameの展開形と正確にマッチしなければならないことに注意。この関数は、同じファイルにたいする他の名前は、認識しないだろう。

(get-file-buffer "buffers.texi")
    ⇒ #<buffer buffers.texi>

特殊な状況下では、複数のバッファーが同じファイル名をvisitすることがあり得る。そのような場合、この関数はバッファーリスト内の最初に該当するバッファーをリターンする。

Function: find-buffer-visiting filename &optional predicate: これはget-file-bufferと似ているが、そのファイルを違う名前でvisitしているかもしれないすべてのバッファーをリターンする。つまり、バッファーのbuffer-file-nameはfilenameの展開形式と正確にマッチする必要はなく、同じファイルを参照することだけが要求される。predicateが非nilの場合、それはfilenameをvisitしているバッファーを1つの引数とする関数であること。そのバッファーにたいして、predicateが非nilをリターンした場合のみ、適切なリターン値と判断される。リターンすべき適切なバッファーが見つからない場合、find-buffer-visitingはnilをリターンする。

Command: set-visited-file-name filename &optional no-query along-with-file

filenameが非空文字列の場合、この関数はカレントバッファーにvisitされているファイルの名前を、filenameに変更する(バッファーがファイルをvisitしていない場合は、visitするファイルとしてfilenameを与える)。そのバッファーにたいする次回の保存では、新たに指定されたファイルに保存されるだろう。

このコマンドは、たとえそのバッファーのコンテンツがその前にvisitされていたファイルとマッチしていても、(Emacsが関知するかぎり)filenameのコンテンツとはマッチしないので、バッファーが変更されている(modified)とマークする。これは、その名前がすでに使用されていなければ、新たなファイル名に対応してバッファーをリネームする。

filenameがnil、または空文字列の場合、それは“visitされているファイルがない”ことを意味する。この場合、set-visited-file-nameはバッファーの変更フラグを変更することなく、そのバッファーがファイルをvisitしていないとマークする。

この関数はfilenameをvisitしているバッファーがすでに存在する場合は、通常はユーザーに確認を求める。しかし、no-queryが非nilの場合は、この質問を行わない。filenameをvisitしているバッファーがすでに存在し、かつユーザーが承認、またはno-queryが非nilの場合、この関数は中に数字が入った‘<…>’をfilenameに追加して、新たなバッファーの名前を一意にする。

along-with-fileが非nilの場合、それは前にvisitされていたファイルがfilenameにリネームされたと想定することを意味する。この場合、コマンドはバッファーの修正フラグを変更せず、そのバッファーの記録されている最終ファイル変更時刻をvisited-file-modtimeが報告する時刻(バッファーの変更 Timeを参照)で変更もしない。along-with-fileがnilの場合、この関数はvisited-file-modtimeが0をリターンした後に、記録済みの最終ファイル変更時刻をクリアーする。

関数set-visited-file-nameがinteractiveに呼び出されたときは、ミニバッファー内でfilenameの入力を求める。

Variable: list-buffers-directory: このバッファーローカル変数は、visitしているファイル名をもたないバッファーにたいして、バッファーリスト中のvisitしているファイル名を表示する場所に表示する文字列を指定する。Diredバッファーは、この変数を使用する。

27.5 バッファーの変更

Emacsは、各バッファーにたいして、バッファーのテキストを変更したかどうかを記録するために、変更フラグ(modified flag)と呼ばれるフラグを管理しています。このフラグは、バッファーのコンテンツを変更すると常にtにセットされ、バッファーを保存したときnilにクリアーされます。したがって、このフラグは保存されていない変更があるかどうかを表します。フラグの値は通常、モードライン内(モードラインで使用される変数を参照)に表示され、保存(バッファーの保存を参照)と自動保存(自動保存を参照)を制御します。

いくつかのLispプログラムは、このフラグを明示的にセットします。たとえば、関数set-visited-file-nameは、このフラグをtにセットします。なぜなら、たとえその前にvisitしていたファイルが変更されていなくても、テキストは新たにvisitされたファイルとマッチしないからです。

バッファーのコンテンツを変更する関数については、テキストで説明されています。

Function: buffer-modified-p &optional buffer: この関数は、バッファーbufferが最後にファイルから読み込まれた、あるいは保存されてから変更されていればt、それ以外ではnilをリターンする。bufferが与えられない場合は、カレントバッファーがテストされる。

Function: set-buffer-modified-p flag

この関数は、flagが非nilならカレントバッファーを変更済みとしてマークし、nilなら未変更としてマークする。

この関数を呼び出すことによる別の効果は、それがカレントバッファーのモードラインの無条件な再表示を引き起こすことである。実際のところ、関数force-mode-line-updateは、以下を行うことにより機能する:

(set-buffer-modified-p (buffer-modified-p))

Function: restore-buffer-modified-p flag: set-buffer-modified-pと同様だが、モードラインにたいする強制的な再表示を行わない。

Command: not-modified &optional arg

このコマンドは、カレントバッファーが変更されておらず、保存する必要がないとマークする。argが非nilの場合、これは変更されているとマークするので、次回の適切なタイミングでバッファーは保存されるだろう。interactiveに呼び出された場合、argはプレフィックス引数である。

この関数は、エコーエリア内にメッセージをプリントするので、プログラム内で使用してはならない。かわりに、set-buffer-modified-p(上記)を使用すること。

Function: buffer-modified-tick &optional buffer: この関数は、bufferの変更カウント(modification-count)をリターンする。これは、バッファーが変更されるたびに増加されるカウンターである。bufferがnil(または省略)の場合は、カレントバッファーが使用される。このカウンターは、時折0にクリアーされ得る。

Function: buffer-chars-modified-tick &optional buffer: この関数は、bufferの文字変更に関わる変更カウントをリターンする。テキストプロパティを変更しても、このカウンターは変化しない。しかし、そのバッファーにテキストが挿入、または削除されるたびに、このカウンターはbuffer-modified-tickによりリターンされるであろう値にリセットされる。buffer-chars-modified-tickを2回呼び出してリターンされる値を比較することにより、その呼び出しの間にバッファー内で文字変更があったかどうかを知ることができる。bufferがnil(または省略)の場合は、カレントバッファーが使用される。

27.6 バッファーの変更 Time

あるファイルをvisitして、そのバッファー内で変更を行って、その一方ではディスク上でファイル自身が変更されたとします。この時点でバッファーを保存すると、ファイル内の変更は上書きされるでしょう。これが正に望んでいる動作のときもありますが、通常は有用な情報が失われてしまいます。したがって、Emacsはファイルを保存する前に、以下で説明する関数を使用して、ファイルの変更時刻をチェックします(ファイルの変更時刻を調べる方法は、ファイルの属性を参照)。

Function: verify-visited-file-modtime &optional buffer

この関数は、buffer(デフォルトはカレントバッファー)にvisitされているファイルにたいして記録されている変更時刻と、オペレーティングシステムにより記録された実際の変更時刻を比較する。これら2つの時刻は、Emacsがそのファイルをvisit、もしくは保存して以降、他のプロセスにより書き込みがされていなければ、等しくなるはずである。

この関数は、実際の最終変更時刻と、Emacsが記録した変更時刻が同じならt、それ以外はnilをリターンする。そのバッファーが記録済みの最終変更時刻をもたない、すなわちvisited-file-modtimeが0をリターンするような場合も、tをリターンする。

これは、たとえvisited-file-modtimeが非0の値をリターンしたとしても、ファイルをvisitしていないバッファーにたいしては、常にtをリターンする。たとえば、diredバッファーにたいして、この関数は常にtをリターンする。また、存在せず、以前に存在したこともなかったファイルをvisitするバッファーにたいしてtをリターンするが、visitしているファイルが削除されたバッファーにたいしてはnilをリターンする。

Function: clear-visited-file-modtime

この関数は、カレントバッファーによりvisitされているファイルの最終変更時刻の記録をクリアーする。結果として、このバッファーにを次回の保存では、ファイルの変更時刻の食い違いは報告されなくなる。

この関数はset-visited-file-name、および変更済みファイルの上書きを防ぐための通常テストを行わない例外的な箇所で呼び出される。

Function: visited-file-modtime

この関数は、カレントバッファーの記録された最終ファイル変更時刻を、(high low microsec picosec)のような形式のリストでリターンする(これは、file-attributesが時刻値をリターンするために使用するフォーマットと同じである。ファイルの属性を参照されたい)。

バッファーが最終変更時刻の記録をもたない場合、この関数は0をリターンする。これが発生するのは、たとえばバッファーがファイルをvisitしていなかったり、clear-visited-file-modtimeで最終変更時刻が明示的にクリアーされた場合である。しかしvisited-file-modtimeは、いくつかの非ファイルバッファーにたいするリストをリターンすることに注意。たとえば、ディレクトリーをリストするDiredバッファーでは、Diredが記録するそのディレクトリーの最終変更時刻がリターンされる。

If the buffer is not visiting a file, this function returns -1.

Function: set-visited-file-modtime &optional time

この関数は、バッファーがvisitしているファイルの最終変更時刻の記録を、timeが非nil、それ以外はvisitしているファイルの最終変更時刻により更新する。

If time is neither nil nor an integer flag returned by visited-file-modtime, it should have the form (high low microsec picosec), the format used by current-time (see section 時刻).

この関数は、バッファーが通常のようにファイルから読み取られたものでない場合や、ファイル自身が害のない既知の理由により変更されている場合に有用である。

Function: ask-user-about-supersession-threat filename

This function is used to ask a user how to proceed after an attempt to modify a buffer visiting file filename when the file is newer than the buffer text. Emacs detects this because the modification time of the file on disk is newer than the last save-time and its contents have changed. This means some other program has probably altered the file.

この関数が正常にリターンするかどうかは、ユーザーの答えに依存する。関数はバッファーの変更が処理された場合は正常にリターンし、バッファーの変更が許可されなかった場合は、データ(filename)とともにエラーfile-supersessionをシグナルする。

この関数は、適切なタイミングでEmacsにより自動的に呼び出される。これは、再定義することによりEmacsをカスタマイズ可能にするために存在する。標準的な定義は、ファイルuserlock.elを参照されたい。

ファイルのロックのファイルロックのメカニズムも参照のこと。

27.7 読み取り専用のバッファー

あるバッファーが読み取り専用(read-only)の場合は、たとえスクロールやナローイングによってファイルのコンテンツのビューを変更しても、そのコンテンツを変更することはできません。

読み取り専用バッファーは、2つのタイプの状況において使用されます:

書き込み保護されたファイルをvisitするバッファーは、通常は読み取り専用になる。
ここでの目的は、ユーザーにたいしてそのファイルへの保存を意図したバッファーの編集が無益、または望ましくないかもしれないことを伝えることである。それにも関わらずバッファーのテキストの変更を望むユーザーは、C-x C-qで読み取り専用フラグをクリアーした後、これを行うことができる。
DiredやRmailのようなモードは、通常の編集コマンドによるコンテンツの変更がおそらく間違いであるようなときに、バッファーを読み取り専用にする。
このようなモードのスペシャルコマンドは、buffer-read-onlyを(letにより)nilにバインドしたり、テキストを変更する箇所ではinhibit-read-onlyをtにバインドする。

Variable: buffer-read-only: This buffer-local variable specifies whether the buffer is read-only. The buffer is read-only if this variable is non-nil. However, characters that have the inhibit-read-only text property can still be modified. See section inhibit-read-only.

Variable: inhibit-read-only

この変数が非nilの場合、読み取り専用バッファー、およびその実際の値に依存して、一部もしくはすべての読み取り専用文字が変更されている。バッファー内の読み取り専用文字とは、テキストプロパティread-onlyが非nilの文字である。テキストプロパティについての詳細は、特殊な意味をもつプロパティを参照のこと。

inhibit-read-onlyがtの場合、すべてのread-only文字プロパティは効果がなくなる。inhibit-read-onlyがリストの場合、read-only文字プロパティがリストのメンバーなら効果がなくなる(比較はeqで行われる)。

Command: read-only-mode &optional arg

これは、バッファーローカルなマイナーモードである、Read Onlyモードにたいするモードコマンドである。このモードが有効なときは、そのバッファーのbuffer-read-onlyは非nilである。無効なときは、そのバッファーのbuffer-read-onlyはnilである。呼び出す際の慣習は、他のマイナーモードコマンドの慣習と同じである(マイナーモード記述の規約を参照)。

このマイナーモードは他のマイナーモードとは異なり、主にbuffer-read-onlyにたいするラッパーの役目を果たし、別個にread-only-mode変数は存在しない。Read Onlyモードが無効なときでも、read-onlyテキストプロパティが非nilの文字は読み取り専用のままである。一時的にすべての読み取り専用ステータスを無視するには、上述のinhibit-read-onlyをバインドすること。

Read Onlyモードを有効にする際、このモードコマンドはオプションview-read-onlyが非nilなら、Viewモードも有効にする。Miscellaneous Buffer Operations in The GNU Emacs Manualを参照のこと。Read Onlyモードを無効にする際に、もしもViewモードが有効なら、Viewモードも無効にする。

Function: barf-if-buffer-read-only &optional position

This function signals a buffer-read-only error if the current buffer is read-only. If the text at position (which defaults to point) has the inhibit-read-only text property set, the error will not be raised.

See section interactiveの使用, for another way to signal an error if the current buffer is read-only.

27.8 バッファーリスト

バッファーリスト(buffer list)とは、すべての生きた(killされていない)バッファーのリストです。このリスト内のバッファーの順序は主に、それぞれのバッファーがウィンドウに表示されたのがどれほど最近なのかにもとづきます。いくつかの関数、特にother-bufferはこの順序を使用します。ユーザーに表示されるバッファーリストも、この順序にしたがいます。

バッファーを作成すると、それはバッファーリストの最後に追加されバッファーをkillすることにより、そのリストから削除されます。ウィンドウに表示するためにバッファーが選択されたとき(ウィンドウ内のバッファーへの切り替えを参照)、あるいはバッファーを表示するウィンドウが選択されたとき(ウィンドウの選択を参照)、そのバッファーは常にこのリストの先頭に移動します。バッファーがバリー(以下のbury-bufferを参照)されたときは、このリストの最後に移動します。バッファーリストを直接操作するために利用できる、Lispプログラマー向けの関数は存在しません。

説明した基本バッファーリスト(fundamental buffer list)に加えて、Emacsはそれぞれのフレームにたいしてローカルバッファーリスト(local buffer list)を保守します。ローカルバッファーリストでは、そのフレーム内で表示されていた(または選択されたウィンドウの)バッファーが先頭になります(この順序は、そのフレームのフレームパラメーターbuffer-listに記録される。バッファーのパラメーターを参照されたい)。そのフレームでは表示されていないフレームは後になるよう、並び順は基本バッファーリストに準じます。

Function: buffer-list &optional frame

この関数は、すべてのバッファーを含むバッファーリストをリターンする(名前がスペースで始まるバッファーも含む)。リストの要素はバッファーの名前ではなく、実際のバッファーである。

frameがフレームの場合は、frameのローカルバッファーリストをリターンする。frameがnil、または省略された場合は、基本バッファーリストが使用される。その場合、そのバッファーを表示するフレームがどれかとは無関係に、もっとも最近に表示、または選択されたバッファーの順になる。

(buffer-list)
     ⇒ (#<buffer buffers.texi>
         #<buffer  *Minibuf-1*> #<buffer buffer.c>
         #<buffer *Help*> #<buffer TAGS>)

;; ミニバッファーの名前が
;;   スペースで始まることに注意!
(mapcar (function buffer-name) (buffer-list))
    ⇒ ("buffers.texi" " *Minibuf-1*"
        "buffer.c" "*Help*" "TAGS")

buffer-listからリターンされるリストは、それ専用に構築されたリストであり、Emacsの内部的なデータ構造ではないし、それを変更してもバッファーの並び順に影響はありません。基本バッファーリスト内のバッファーの並び順を変更したい場合に簡単なのは、以下の方法です:

(defun reorder-buffer-list (new-list)
  (while new-list
    (bury-buffer (car new-list))
    (setq new-list (cdr new-list))))

この方法により、バッファーを失ったり、有効な生きたバッファー以外の何かを追加する危険を犯さずに、リストに任意の並び順を指定できます。

特定のフレームのバッファーリストの並び順や値を変更するには、modify-frame-parametersでそのフレームのbuffer-listパラメーターをセットしてください(フレームパラメーターへのアクセスを参照)。

Function: other-buffer &optional buffer visible-ok frame

この関数は、バッファーリスト中でbuffer以外の最初のバッファーをリターンする。これは通常選択されたウィンドウ(フレームframe、または選択されたフレーム。入力のフォーカスを参照)に、もっとも最近表示された、buffer以外のバッファーである。名前がスペースで始まるバッファーは、考慮されない。

If buffer is not supplied (or if it is not a live buffer), then other-buffer returns the first buffer in the selected frame’s local buffer list. (If frame is non-nil, it returns the first buffer in frame’s local buffer list instead.)

frameが非nilのbuffer-predicateパラメーターをもつ場合は、どのバッファーを考慮すべきかを決定するために、other-bufferはその述語を使用する。これはそれぞれのバッファーごとにその述語を一度呼び出して、値がnilならそのバッファーは無視される。バッファーのパラメーターを参照のこと。

visible-okがnilならば、other-bufferはやむを得ない場合を除き、任意の可視のフレーム上のウィンドウ内で可視のバッファーをリターンすることを避ける。visible-okが非nilの場合は、バッファーがどこかで表示されているかどうかは問題にしない。

適切なバッファーが存在しない場合は、バッファー*scratch*を(必要なら作成して)リターンする。

Function: last-buffer &optional buffer visible-ok frame

この関数は、frameのバッファーリスト内から、buffer以外の最後のバッファーをリターンする。frameが省略、またはnilの場合は、選択されたフレームのバッファーリストを使用する。

引数visible-okは、上述したother-bufferと同様に扱われる。適切なバッファーを見つけられない場合は、バッファー*scratch*がリターンされる。

Command: bury-buffer &optional buffer-or-name

このコマンドは、バッファーリスト内の他のバッファーの並び順を変更することなく、buffer-or-nameをバッファーリストの最後に置く。つまり、このバッファーはother-bufferがリターンする候補で、もっとも期待度が低くなる。引数はバッファー自身か、バッファーの名前を指定できる。

This function operates on each frame’s buffer-list parameter as well as the fundamental buffer list; therefore, the buffer that you bury will come last in the value of (buffer-list frame) and in the value of (buffer-list). In addition, it also puts the buffer at the end of the list of buffers of the selected window (see section ウィンドウのヒストリー) provided it is shown in that window.

If buffer-or-name is nil or omitted, this means to bury the current buffer. In addition, if the current buffer is displayed in the selected window, this makes sure that the window is either deleted or another buffer is shown in it. More precisely, if the selected window is dedicated (see section 専用のウィンドウ) and there are other windows on its frame, the window is deleted. If it is the only window on its frame and that frame is not the only frame on its terminal, the frame is dismissed by calling the function specified by frame-auto-hide-function (see section ウィンドウのquit). Otherwise, it calls switch-to-prev-buffer (see section ウィンドウのヒストリー) to show another buffer in that window. If buffer-or-name is displayed in some other window, it remains displayed there.

あるバッファーにたいして、それを表示するすべてのウィンドウでバッファーを置き換えるには、replace-buffer-in-windowsを使用する。バッファーとウィンドウを参照のこと。

Command: unbury-buffer: このコマンドは、選択されたフレームのローカルバッファーリストの最後のバッファーに切り替える。より正確には、選択されたウィンドウ内で、last-buffer(上記参照)がリターンするバッファーを表示するために、関数switch-to-bufferを呼び出す(ウィンドウ内のバッファーへの切り替えを参照)。

Variable: buffer-list-update-hook: これは、バッファーリストが変更されたときは、常に実行されるノーマルフックである。(暗黙的に)このフックを実行する関数はget-buffer-create(バッファーの作成を参照)、rename-buffer(バッファーの名前を参照)、kill-buffer(バッファーのkillを参照)、bury-buffer(上記参照)、select-window(ウィンドウの選択を参照)である。

27.9 バッファーの作成

このセクションでは、バッファーを作成する2つのプリミティブについて説明します。get-buffer-createは、指定された名前の既存バッファーが見つからない場合は作成します。generate-new-bufferは、常に新たにバッファーを作成して、それに一意な名前を与えます。

バッファーを作成するために使用できる他の関数には、with-output-to-temp-buffer(一時的な表示を参照)、およびcreate-file-buffer(ファイルのvisitを参照)が含まれます。サブプロセスの開始によっても、バッファーを作成することができます(プロセスを参照)。

Function: get-buffer-create buffer-or-name

この関数は、buffer-or-nameという名前のバッファーをリターンする。リターンされたバッファーはカレントにならない — この関数はカレントがどのバッファーであるかを変更しない。

buffer-or-nameは文字列、または既存バッファーのいずれかでなければならない。これが文字列で、かつ既存の生きたバッファーの名前の場合、get-buffer-createはそのバッファーをリターンする。そのようなバッファーが存在しなければ、新たにバッファーを作成する。buffer-or-nameが文字列ではなくバッファーの場合、たとえそのバッファーが生きていなくても、与えられたバッファーをリターンする。

(get-buffer-create "foo")
     ⇒ #<buffer foo>

新たに作成されたバッファーにたいするメジャーモードは、Fundamentalモードにセットされる(変数major-modeのデフォルト値は、より高いレベルで処理される。Emacsがメジャーモードを選択する方法を参照されたい)。名前がスペースで始まる場合、そのバッファーのアンドゥ情報の記録は、初期状態では無効である(アンドゥを参照)。

Function: generate-new-buffer name

この関数は、新たに空のバッファーを作成してリターンするが、それをカレントにはしない。バッファーの名前は、関数generate-new-buffer-nameにnameを渡すことにより生成される(バッファーの名前を参照)。つまり、nameという名前のバッファーが存在しなければ、それが新たなバッファーの名前になり、その名前が使用されていた場合は、‘<n>’という形式のサフィックスがnameに追加される。ここでnは整数である。

nameが文字列でない場合は、エラーがシグナルされる。

(generate-new-buffer "bar")
     ⇒ #<buffer bar>

(generate-new-buffer "bar")
     ⇒ #<buffer bar<2>>

(generate-new-buffer "bar")
     ⇒ #<buffer bar<3>>

新たなバッファーにたいするメジャーモードは、Fundamentalモードにセットされる。変数major-modeのデフォルト値は、より高いレベルで処理される。Emacsがメジャーモードを選択する方法を参照のこと。

27.10 バッファーのkill

バッファーのkillにより、そのバッファーの名前はEmacsにとって未知の名前となり、そのバッファーが占めていたメモリースペースは、他の用途に使用できるようになります。

バッファーに対応するバッファーオブジェクトは、それを参照するものがあればkillされても存在し続けますが、それをカレントにしたり表示することができないよう、特別にマークされます。とはいえ、killされたバッファーの同一性は保たれるので、2つの識別可能なバッファーをkillした場合、たとえ両方死んだバッファーであっても、eqによる同一性は残ります。

あるウィンドウ内においてカレント、あるいは表示されているバッファーをkillした場合、Emacsはかわりに他の何らかのバッファーを自動的に選択、または表示します。これは、バッファーのkillにより、カレントバッファーが変更されることを意味します。したがって、バッファーをkillする際は、(killされるバッファーがカレントを偶然知っていた場合を除き)カレントバッファーの変更に関しても、事前に注意を払うべきです。カレントバッファーを参照してください。

1つ以上のインダイレクトバッファー(インダイレクトバッファーを参照) のベースとなるバッファーをkillした場合は、インダイレクトバッファーも同様に自動的にkillされます。

バッファーのbuffer-nameがnilの場合のみ、バッファーはkillされる。killされていないバッファーは生きた(live)バッファーと呼ばれる。あるバッファーにたいして、そのバッファーが生きているか、またはkillされているかを確認するには、buffer-live-pを使用する(下記参照)。

Command: kill-buffer &optional buffer-or-name

この関数は、バッファーbuffer-or-nameをkillして、そのバッファーのメモリーを他の用途のために開放、またはオペレーティングシステムに返却する。buffer-or-nameがnil、または省略された場合は、カレントバッファーをkillする。

Any processes that have this buffer as the process-buffer are sent the SIGHUP (hangup) signal, which normally causes them to terminate. See section プロセスへのシグナルの送信.

バッファーがファイルをvisitしていて、かつ保存されていない変更が含まれる場合、kill-bufferはバッファーをkillする前に、ユーザーにたいして確認を求める。これは、kill-bufferがinteractiveに呼び出されていなくても、行われる。この確認要求を抑制するには、kill-bufferの呼び出し前に、変更フラグ(modified flag)をクリアーすればよい。バッファーの変更を参照のこと。

killされるバッファーをカレントで表示しているすべてのバッファーをクリーンアップするために、この関数はreplace-buffer-in-windowsを呼び出す。

すでに死んでいるバッファーをkillしても、効果はない。

この関数は、実際にバッファーをkillした場合は、tをリターンする。ユーザーが確認で拒否を選択、またはbuffer-or-nameがすでに死んでいる場合は、nilをリターンする。

(kill-buffer "foo.unchanged")
     ⇒ t
(kill-buffer "foo.changed")

---------- Buffer: Minibuffer ----------
Buffer foo.changed modified; kill anyway? (yes or no) yes
---------- Buffer: Minibuffer ----------

     ⇒ t

Variable: kill-buffer-query-functions: 保存されていない変更について確認を求める前に、kill-bufferはリストkill-buffer-query-functions内の関数を、出現順に引数なしで呼び出す。 Before confirming unsaved changes, calls the functions in the list , in order of appearance, with no arguments. それらが呼び出される際には、killされるバッファーがカレントになる。この機能は、これらの関数がユーザーに確認を求めるというアイデアが元となっている。これらの関数のいずれかがnilをリターンした場合、kill-bufferはそのバッファーの命を奪わない。

Variable: kill-buffer-hook: これは、尋ねることになっている質問をすべて終えた後、実際にバッファーをkillする直前に、kill-bufferにより実行されるノーマルフックである。この変数は永続的にローカルであり、メジャーモードの変更により、そのローカルバインディングはクリアーされない。

User Option: buffer-offer-save: This variable, if non-nil in a particular buffer, tells save-buffers-kill-emacs to offer to save that buffer, just as it offers to save file-visiting buffers. If save-some-buffers is called with the second optional argument set to t, it will also offer to save the buffer. Lastly, if this variable is set to the symbol always, both save-buffers-kill-emacs and save-some-buffers will always offer to save. See Definition of save-some-buffers. The variable buffer-offer-save automatically becomes buffer-local when set for any reason. See section バッファーローカル変数.

Variable: buffer-save-without-query: 特定のバッファーにおいてこの変数が非nilの場合、save-buffers-kill-emacsおよびsave-some-buffersは、(バッファーが変更されていれば)ユーザーに確認を求めることなく、そのバッファーを保存する。何らかの理由によりこの変数をセットする際は、自動的にバッファーローカルになる。

Function: buffer-live-p object: この関数は、objectが生きたバッファー(killされていないバッファー)ならt、それ以外はnilをリターンする。

27.11 インダイレクトバッファー

インダイレクトバッファー(indirect buffer: 間接バッファー)とは、ベースバッファー(base buffer)と呼ばれる他のバッファーとテキストを共有します。いくつかの点において、インダイレクトバッファーはファイル間でのシンボリックリンクに類似しています。ベースバッファー自身は、インダイレクトバッファーでない可能性があります。

インダイレクトバッファーのテキストは、常にベースバッファーのテキストと同一です。編集により一方が変更されると、それは即座に他方のバッファーから可視になります。これには文字自体に加えて、テキストプロパティも同様に含まれます。

他のすべての観点において、インダイレクトバッファーとそのベースバッファーは、完全に別物です。それらは別の名前、独自のポイント値、ナローイング、マーカー、オーバーレイ、メジャーモード、バッファーローカルな変数バインディングをもちます(ただし、どちらかのバッファーでのテキストの挿入や削除を行うと、両方のバッファーでマーカーとオーバーレイの再配置が行われる)。

インダイレクトバッファーはファイルをvisitできませんが、ベースバッファーは可能です。インダイレクトバッファーの保存を試みた場合、実際にはベースバッファーが保存されます。

インダイレクトバッファーをkillしても、ベースバッファーに影響はありません。ベースバッファーをkillすると、インダイレクトバッファーはkillされて、再びカレントバッファーになることはできません。

Command: make-indirect-buffer base-buffer name &optional clone

これは、ベースバッファーがbase-bufferであるような、nameという名前のインダイレクトバッファーを作成してリターンする。引数base-bufferは生きたバッファー、または既存バッファーの名前(文字列)を指定できる。nameが既存バッファーの名前の場合は、エラーがシグナルされる。

If clone is non-nil, then the indirect buffer originally shares the state of base-buffer such as major mode, minor modes, buffer local variables and so on. If clone is omitted or nil the indirect buffer’s state is set to the default state for new buffers.

base-bufferがインダイレクトバッファーの場合は、新たなバッファーのベースとして、それのベースバッファーが使用される。さらに、cloneが非nilならば、初期状態はbase-bufferではなく、実際のベースバッファーからコピーされる。

Command: clone-indirect-buffer newname display-flag &optional norecord

この関数は、カレントバッファーのベースバッファーを共有するインダイレクトバッファーを新たに作成し、カレントバッファーの残りの属性をコピーしてリターンする(カレントバッファーがインダイレクトバッファーでない場合は、それがベースバッファーとして使用される)。

display-flagが非nilの場合、それはpop-to-bufferを呼び出すことにより新しいバッファーを表示することを意味する。norecordが非nilの場合、それは新しいバッファーをバッファーリストの先頭に置かないことを意味する。

Function: buffer-base-buffer &optional buffer: この関数は、buffer(デフォルトはカレントバッファー)のベースバッファーをリターンする。bufferがインダイレクトバッファーでない場合、値はnilになり、それ以外では値は他のバッファーとなり、このバッファーがインダイレクトバッファーではあり得ない。

27.12 2つのバッファー間でのテキストの交換

特別なモードでは、ユーザーが同一のバッファーから複数の非常に異なったテキストにアクセスできるようにしなければならない場合があります。たとえば、バッファーのテキストのサマリーを表示して、ユーザーがそのテキストにアクセスできるようにする場合です。

これは、(ユーザーがテキストを編集した際には同期を保つ)複数バッファーや、ナローイング(ナローイングを参照)により実装することができるかもしれません。しかし、これらの候補案はときに退屈になりがちであり、特にそれぞれのテキストタイプが正しい表示と編集コマンドを提供するために高価なバッファーグローバル操作を要求する場合には、飛び抜けて高価になる場合があります。

Emacsは、そのようなモードにたいする、別の機能を提供します。buffer-swap-textを使用すれば、2つのバッファー間でバッファーテキストを素早く交換することができます。この関数は、テキストの移動は行わず、異なるテキスト塊(text chunk)をポイントするように、バッファーオブジェクトの内部的なデータ構造だけを変更するので、非常に高速です。これを使用することにより、2つ以上のバッファーグループから、個々のバッファーのコンテンツすべてを併せもつような、単一の仮想バッファー(virtual buffer)が実在するように、見せかけることができます。

Function: buffer-swap-text buffer

この関数は、カレントバッファーのテキストと、引数bufferのテキストを交換する。2つのバッファーのいずれか一方がインダイレクトバッファー(インダイレクトバッファーを参照)、またはインダイレクトバッファーのベースバッファーの場合は、エラーをシグナルする。

バッファーテキストに関連するすべてのバッファープロパティ、つまりポイントとマークの位置、すべてのマーカーとオーバーレイ、テキストプロパティ、アンドゥリスト、enable-multibyte-charactersフラグの値(enable-multibyte-charactersを参照)等も、同じように交換される。

Warning: If this function is called from within a save-excursion form, the current buffer will be set to buffer upon leaving the form, since the marker used by save-excursion to save the position and buffer will be swapped as well.

ファイルをvisitしているバッファーにbuffer-swap-textを使用した場合は、交換されたテキストではなく、そのバッファーの元のテキストを保存するようにフックをセットアップするべきです。write-region-annotate-functionsは、正にこの目的のために機能します。そのバッファーのbuffer-saved-sizeを、おそらく交換されたテキストにたいする変更が自動保存に干渉しないであろう、-2にセットするべきでしょう。

27.13 バッファーのギャップ

Emacsのバッファーは、挿入と削除を高速にするために、不可視のギャップ(gap)を使用して実装されています。挿入はギャップ部分を充填し、削除はギャップを追加することにより機能します。もちろん、これは最初にギャップを挿入もしくは削除の部位(locus)に移動しなければならないことを意味します。Emacsは、ユーザーが挿入、または削除を試みたときだけ、ギャップを移動します。大きなバッファー内の遠く離れた位置で編集した後、他の箇所での最初の編集コマンドに無視できない遅延が発生する場合があるのは、これが理由です。

このメカニズムは暗に機能するものであり、Lispコードはギャップのカレント位置に影響されるべきでは決してありませんが、以下の関数はギャップ状態に関する情報の取得に利用できます。

Function: gap-position: この関数は、カレントバッファー内のギャップのカレント位置をリターンする。

Function: gap-size: この関数は、カレントバッファー内のギャップのサイズをリターンする。

28 ウィンドウ

このチャプターでは、Emacsのウィンドウに関連する関数と変数について説明します。Emacsが利用可能なスクリーン領域にウィンドウが割り当てられる方法については、フレームを参照してください。ウィンドウ内にテキストが表示される方法についての情報は、Emacsのディスプレー表示を参照してください。

28.1 Emacsウィンドウの基本概念		ウィンドウ使用についての基本情報。
28.2 ウィンドウとフレーム		ウィンドウとそれらが表示されるフレームとの関連。
28.3 ウィンドウのサイズ		ウィンドウのサイズへのアクセス。
28.4 ウィンドウのリサイズ		ウィンドウのサイズの変更。
28.5 Preserving Window Sizes		Preserving the size of windows.
28.6 ウィンドウの分割		新たなウィンドウの作成。
28.7 ウィンドウの削除		フレームからのウィンドウの削除。
28.8 ウィンドウの再結合		ウィンドウの分割や削除時のフレームレイアウトの保存。
28.9 ウィンドウの選択		選択されたウィンドウとは、編集を行っているウィンドウである。
28.10 ウィンドウのサイクル順		既存のウィンドウ間の移動。
28.11 バッファーとウィンドウ		それぞれのウィンドウは、バッファーのコンテンツを表示する。
28.12 ウィンドウ内のバッファーへの切り替え		バッファー切り替えのための、より高レベルな関数。
28.13 表示するウィンドウの選択		バッファーを表示するウィンドウの選択方法。
28.14 `display-buffer`にたいするアクション関数		`display-buffer`用のサブルーチン。
28.15 バッファー表示の追加オプション		バッファー表示方法に影響する拡張オプション。
28.16 ウィンドウのヒストリー		それぞれのウィンドウは、表示されていたバッファーを記憶する。
28.17 専用のウィンドウ		特定のウィンドウ内で他のバッファーの表示を無効にする。
28.18 ウィンドウのquit		以前に表示していたバッファーの状態をリストアする方法。
28.19 Side Windows		Special windows on a frame’s sides.
28.20 Atomic Windows		Preserving parts of the window layout.
28.21 ウィンドウとポイント		それぞれのウィンドウは、自身の位置とポイントをもつ。
28.22 ウィンドウの開始位置と終了位置		ウィンドウ内でスクリーン表示されるテキストを表すバッファー位置。
28.23 テキスト的なスクロール		ウィンドウを通じたテキストの上下移動。
28.24 割り合いによる垂直スクロール		ウィンドウ上のコンテンツの上下移動。
28.25 水平スクロール		ウィンドウ上のコンテンツの横移動。
28.26 座標とウィンドウ		座標からウィンドウへの変換。
28.27 Mouse Window Auto-selection		Automatically selecting windows with the mouse.
28.28 ウィンドウの構成		スクリーンの情報の保存とリストア。
28.29 ウィンドウのパラメーター		ウィンドウへの追加情報の割り当て。
28.30 ウィンドウのスクロールと変更のためのフック		スクロール、ウィンドウのサイズ変更、ある特定のしきい値を超えたときに行われる再表示、ウィンドウ設定の変更にたいするフック。

28.1 Emacsウィンドウの基本概念

ウィンドウ(window)とは、任意のバッファーを表示するために使用される、スクリーンの領域です。Emacs Lispでは、ウィンドウはスペシャルLispオブジェクトとして表現されます。

ウィンドウは、フレームへとグループ化されます(フレームを参照)。それぞれのフレームは、最低でも1つのウィンドウを含みます。ユーザーは、複数のバッファーを一度に閲覧するために、それを複数のオーバーラップしないウィンドウに分割することができます。Lispプログラムは、さまざまな目的にたいして、複数のウィンドウを使用できます。たとえばRmailでは、1つのウィンドウでメッセージタイトル、もう一方のウィンドウで選択したメッセージのコンテンツを閲覧できます。

Emacsは、グラフィカルなデスクトップ環境や、X Window Systemのようなウィンドウシステムとは異なる意味で、“ウィンドウ(window)”という単語を使用します。EmacsがX上で実行されているときは、XのグラフィカルなXウィンドウは、Emacsでの(1つ以上のEmacsウィンドウを含んだ)フレームになります。Emacsがテキスト端末上で実行されているときは、フレームが端末スクリーン全体を占有します。

Xのウィンドウとは異なり、Emacsのウィンドウはタイル表示(tiled)され、フレームの領域内でオーバーラップされることは決してありません。あるウィンドウが作成、リサイズ、削除されるとき、変更されたウィンドウスペースの変更は各ウィンドウの調整により取得・譲与されるので、そのフレームの総領域に変化はありません。

Function: windowp object: この関数は、objectがウィンドウ(バッファーの表示有無に関わらず)ならt、それ以外はnilをリターンする。

生きたウィンドウ(live window)とは、あるフレーム内で実際にバッファーを表示しているウィンドウのことです。

Function: window-live-p object: この関数は、objectが生きたウィンドウならt、それ以外はnilをリターンする。生きたウィンドウとは、バッファーを表示するウィンドウのこと。

各フレーム内のウィンドウは、ウィンドウツリー(window tree)内へと組織化されます。ウィンドウとフレームを参照してください。それぞれのウィンドウツリーのリーフノード(leaf nodes)は、実際にバッファーを表示している生きたウィンドウです。ウィンドウツリーの内部ノード(internal node)は内部ウィンドウ(internal windows)と呼ばれ、これらは生きたウィンドウではありません。

有効なウィンドウ(valid window)とは、生きたウィンドウか、内部ウィンドウのいずれかです。有効なウィンドウにたいしては、それを削除(delete)、すなわちそのウィンドウのフレームから削除することができます(ウィンドウの削除を参照)。その場合、それは有効なウィンドウではなくなりますが、それを表すLispオブジェクトは依然として他のLispオブジェクトから参照されたままかもしれません。削除されたウィンドウは、保存されたウィンドウ設定(window configuration)をリストアすることにより、再び有効になるかもしれません(ウィンドウの構成を参照)。

window-valid-pにより、削除されたウィンドウから有効なウィンドウを区別できます。

Function: window-valid-p object: この関数は、objectが生きたウィンドウ、またはウィンドウツリー内の内部ウィンドウの場合は、tをリターンする。それ以外(objectが削除されたウィンドウの場合も含む)は、nilをリターンする。

In each frame, at any time, exactly one Emacs window is designated as selected within the frame. For the selected frame, that window is called the selected window—the one in which most editing takes place, and in which the cursor for selected windows appears (see section カーソルのパラメーター). Keyboard input that inserts or deletes text is also normally directed to this window. The selected window’s buffer is usually also the current buffer, except when set-buffer has been used (see section カレントバッファー). As for non-selected frames, the window selected within the frame becomes the selected window if the frame is ever selected. See section ウィンドウの選択.

Function: selected-window: この関数は、選択されたウィンドウをリターンする(これは常に生きたウィンドウである)。

Sometimes several windows collectively and cooperatively display a buffer, for example, under the management of Follow Mode (see (emacs)Follow Mode), where the windows together display a bigger portion of the buffer than one window could alone. It is often useful to consider such a window group as a single entity. Several functions such as window-group-start (see section ウィンドウの開始位置と終了位置) allow you to do this by supplying, as an argument, one of the windows as a stand in for the whole group.

Function: selected-window-group

When the selected window is a member of a group of windows, this function returns a list of the windows in the group, ordered such that the first window in the list is displaying the earliest part of the buffer, and so on. Otherwise the function returns a list containing just the selected window.

The selected window is considered part of a group when the buffer local variable selected-window-group-function is set to a function. In this case, selected-window-group calls it with no arguments and returns its result (which should be the list of windows in the group).

28.2 ウィンドウとフレーム

ウィンドウはそれぞれ、正確に1つのフレームに属します(フレームを参照)。

Function: window-frame &optional window: この関数は、ウィンドウwindowが属するフレームをリターンする。windowがnilの場合のデフォルトは、選択されたウィンドウである。

Function: window-list &optional frame minibuffer window

この関数は、フレームframeに属する、生きたウィンドウのリストをリターンする。frameが省略、またはnilの場合のデフォルトは、選択されたフレームである。

オプション引数minibufferは、リターンされるリストにミニバッファーウィンドウを含めるべきかどうかを指定する。minibufferがtの場合は、ミニバッファーウィンドウが含まれる。minibufferがnil、または省略された場合は、ミニバッファーウィンドウがアクティブのときだけ含まれる。minibufferがnilとt以外の場合、ミニバッファーウィンドウは含まれない。

オプション引数windowが非nilの場合、それは指定されたフレーム上の生きたウィンドウであること。その場合は、windowがリターンされるリストの最初の要素になる。windowが省略、またはnilの場合は、そのフレームの選択されたウィンドウが最初の要素になる。

同一フレーム内のウィンドウは、リーフノード(leaf nodes)が生きたウィンドウであるような、ウィンドウツリー(window tree)内に組織化されます。ウィンドウツリーの内部ノード(internal nodes)は生きたウィンドウではありません。これらのウィンドウは、生きたウィンドウ間の関係を組織化するという目的のために存在します。ウィンドウツリーのルートノード(root node)は、ルートウィンドウ(root window)と呼ばれます。ルートノードは生きたウィンドウ(そのフレームにウィンドウが1つだけの場合)、または内部ウィンドウのいずれかです。

ミニバッファーウィンドウ(ミニバッファーのウィンドウを参照)は、そのフレームがミニバッファーだけのフレームでない限り、そのフレームのウィンドウツリーの一部にはなりません。にもかかわらず、このセクションのほとんどの関数は、引数としてミニバッファーウィンドウを受け付けます。さらにこのセクションの最後に説明する関数window-treeは、実際のウィンドウツリーと並列してミニバッファーウィンドウをリストします。

Function: frame-root-window &optional frame-or-window: この関数は、frame-or-windowにたいするルートウィンドウをリターンする。引数frame-or-windowは、ウィンドウかフレームのいずれかであること。これが省略、またはnilの場合のデフォルトは、選択されたフレームである。frame-or-windowがウィンドウの場合、リターン値はそのウィンドウのフレームのルートウィンドウである。

ウィンドウが分割(split)されているときは、以前は1つだった2つの生きたウィンドウが存在します。これらのうちの一方は、元のウィンドウと同じLispウィンドウオブジェクトとして表され、もう一方は新たに作成されたLispウィンドウオブジェクトとして表されます。これらの生きたウィンドウは両方とも、単一の内部ウィンドウの子ウィンドウ(child windows)として、ウィンドウツリーのリーフノードになります。もし必要なら、Emacsはこの内部ウィンドウを自動的に作成します。この内部ウィンドウは親ウィンドウ(parent window)とも呼ばれ、ウィンドウツリー内の適切な位置に配置されます。同じ親を共有するウィンドウセットは、兄弟(sibling)と呼ばれます。

Function: window-parent &optional window: この関数は、windowの親ウィンドウ(parent window)をリターンする。windowが省略、またはnilの場合のデフォルトは、選択されたウィンドウである。windowが親をもたない(ミニバッファーウィンドウやそのフレームのルートウィンドウ)場合、リターン値はnilである。

内部ウィンドウはそれぞれ、常に最低でも2つの子ウィンドウをもちます。ウィンドウ削除によりこの数値が1になった場合、Emacsは自動的に内部ウィンドウを削除して、その残った単一の子ウィンドウがウィンドウツリー内のその位置に配置されます。

子ウィンドウはそれぞれ生きたウィンドウ、または(次に自身の子ウィンドウをもつであろう)内部ウィンドウのいずれかです。したがって、各内部ウィンドウは、最終的にはその内部ウィンドウの子孫であるような生きたウィンドウにより占有される領域を結合した、特定の矩形スクリーン領域(screen area)を占有すると考えることができます。

内部ウィンドウそれぞれにたいして、近接する子たちのスクリーン領域は、垂直(vertically)または水平(horizontally)のいずれかにより整列されます(両方で整列されることはない)。子ウィンドウが他の子ウィンドウと上下に整列される場合、それらは垂直コンビネーション(vertical combination)、左右に整列される場合は水平コンビネーション(horizontal combination)を形成すると表現されます。以下の例で考えてみましょう:

     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

このフレームのルートウィンドウは、内部ウィンドウW1です。これの子ウィンドウは、生きたウィンドウW2と内部ウィンドウW3からなる水平コンビネーションを形成します。W3の子ウィンドウは、生きたウィンドウW4とW5からなる垂直コンビネーションを形成します。したがって、このウィンドウツリー内の生きたウィンドウはW2、W4、およびW5です。

以下の関数は、内部ウィンドウの子ウィンドウ、および子ウィンドウの兄弟を取得するのに使用できます。

Function: window-top-child &optional window: この関数は、内部ウィンドウwindowの子ウィンドウが垂直コンビネーションを形成する場合は、windowの一番上の子ウィンドウをリターンする。他のタイプのウィンドウにたいするリターン値はnilである。

Function: window-left-child &optional window: この関数は、内部ウィンドウwindowの子ウィンドウが水平コンビネーションを形成する場合は、windowの一番左の子ウィンドウをリターンする。他のタイプのウィンドウにたいするリターン値はnilである。

Function: window-child window: この関数は、内部ウィンドウwindowの最初の子ウィンドウをリターンする。これは、垂直コンビネーションにたいしては一番上、水平コンビネーションにたいしては一番左の子ウィンドウである。windowが生きたウィンドウの場合、リターン値はnilである。

Function: window-combined-p &optional window horizontal

この関数は、windowが垂直コンビネーションの一部である場合のみ、非nilをリターンする。windowが省略、またはnilの場合のデフォルトは、選択されたウィンドウである。

オプション引数horizontalが非nilならば、windowが水平コンビネーションの一部である場合のみ非nilをリターンすることを意味する。

Function: window-next-sibling &optional window: この関数は、ウィンドウwindowの次の兄弟をリターンする。省略またはnilの場合、windowのデフォルトは選択されたウィンドウになる。windowが、その親の最後の子の場合、リターン値はnilである。

Function: window-prev-sibling &optional window: この関数は、ウィンドウwindowの前の兄弟をリターンする。省略またはnilの場合、windowのデフォルトは選択されたウィンドウになる。windowが、その親の最初の子の場合、リターン値はnilである。

関数window-next-siblingおよびwindow-prev-siblingを、ウィンドウのサイクル順(ウィンドウのサイクル順を参照)において次、または前のウィンドウをリターンする関数next-windowおよびprevious-windowと混同しないでください。

The following functions can be useful to locate a window within its frame.

Function: frame-first-window &optional frame-or-window: この関数は、frame-or-windowにより指定されたフレームの、左上隅の生きたウィンドウをリターンする。引数frame-or-windowでは、ウィンドウか生きたフレームを示さなければならず、デフォルトは選択されたフレームである。frame-or-windowがウィンドウを指定する場合、この関数はそのウィンドウのフレームの最初のウィンドウをリターンする。前の例のフレームが(frame-first-window)に指定されたとするならば、W2がリターンされる。

Function: window-at-side-p &optional window side

This function returns t if window is located at side of its containing frame. The argument window must be a valid window and defaults to the selected one. The argument side can be any of the symbols left, top, right or bottom. The default value nil is handled like bottom.

Note that this function disregards the minibuffer window (see section ミニバッファーのウィンドウ). Hence, with side equal to bottom it may return t also when the minibuffer window appears right below window.

Function: window-in-direction direction &optional window ignore sign wrap mini

この関数は、ウィンドウwindow内の位置window-pointから、方向directionにあるもっとも近い生きたウィンドウをリターンする。引数directionはabove、below、left、rightのいずれかでなければならない。オプション引数windowは生きたウィンドウを示さなければならず、デフォルトは選択されたウィンドウである。

この関数は、パラメーターno-other-windowが非nilのウィンドウをリターンしない(ウィンドウのパラメーターを参照)。もっとも近いウィンドウのno-other-windowパラメーターが非nilの場合、この関数は指定された方向でno-other-windowパラメーターがnilの、他のウィンドウを探す。オプション引数ignoreが非nilの場合は、たとえno-other-windowパラメーターが非nilのウィンドウでも、リターンされ得る。

オプション引数signが負の数値の場合、それは参照位置としてwindow-pointのかわりに、windowの右端、または下端を使用することを意味する。signが正の数値の場合、それは参照位置としてwindowの左端、または上端を使用することを意味する。

If the optional argument wrap is non-nil, this means to wrap direction around frame borders. For example, if window is at the top of the frame and direction is above, then this function usually returns the frame’s minibuffer window if it’s active and a window at the bottom of the frame otherwise.

If the optional argument mini is nil, this means to return the minibuffer window if and only if it is currently active. If mini is non-nil, this function may return the minibuffer window even when it’s not active. However, if wrap is non-nil, it always acts as if mini were nil.

適切なウィンドウが見つからない場合、この関数はnilをリターンする。

Don’t use this function to check whether there is no window in direction. Calling window-at-side-p described above is a much more efficient way to do that.

The following function allows the entire window tree of a frame to be retrieved:

Function: window-tree &optional frame

この関数は、フレームframeにたいするウィンドウツリーを表すリストをリターンする。frameが省略、またはnilの場合のデフォルトは、選択されたフレームである。

リターン値は、(root mini)という形式のリストである。ここでrootはそのフレームのウィンドウツリーのルートウィンドウ、miniはそのフレームのミニバッファーウィンドウを表す。

ルートウィンドウが生きている場合、rootはそのウィンドウ自身である。それ以外では、rootはリスト(dir edges w1 w2 ...)である。ここでdirは水平コンビネーションならnil、垂直コンビネーションならtとなり、edgesはそのコンビネーションのサイズと位置を与え、残りの要素は子ウィンドウである。子ウィンドウはそれぞれ、同じようにウィンドウオブジェクト(生きたウィンドウにたいして)、または上記フォーマットと同じ形式のリスト(内部ウィンドウにたいして)かもしれない。edges要素はwindow-edgesがリターンする値のような、リスト(left top right bottom)である(座標とウィンドウを参照)。

28.3 ウィンドウのサイズ

以下の図は、生きたウィンドウの構造を示しています:

        ____________________________________________
       |______________ Header Line ______________|RD| ^
     ^ |LS|LM|LF|                       |RF|RM|RS|  | |
     | |  |  |  |                       |  |  |  |  | |
Window |  |  |  |       Text Area       |  |  |  |  | Window
Body | |  |  |  |     (Window Body)     |  |  |  |  | Total
Height |  |  |  |                       |  |  |  |  | Height
     | |  |  |  |<- Window Body Width ->|  |  |  |  | |
     v |__|__|__|_______________________|__|__|__|  | |
       |_________ Horizontal Scroll Bar _________|  | |
       |_______________ Mode Line _______________|__| |
       |_____________ Bottom Divider _______________| v
        <---------- Window Total Width ------------>

At the center of the window is the text area, or body, where the buffer text is displayed. The text area can be surrounded by a series of optional areas. On the left and right, from innermost to outermost, these are the left and right fringes, denoted by LF and RF (see section フリンジ); the left and right margins, denoted by LM and RM in the schematic (see section マージン内への表示); the left or right vertical scroll bar, only one of which is present at any time, denoted by LS and RS (see section スクロールバー); and the right divider, denoted by RD (see section ウィンドウディバイダー). At the top of the window is the header line (see section ウィンドウのヘッダーライン). At the bottom of the window are the horizontal scroll bar (see section スクロールバー); the mode line (see section モードラインのフォーマット); and the bottom divider (see section ウィンドウディバイダー).

Emacs provides miscellaneous functions for finding the height and width of a window. The return value of many of these functions can be specified either in units of pixels or in units of lines and columns. On a graphical display, the latter actually correspond to the height and width of a default character specified by the frame’s default font as returned by frame-char-height and frame-char-width (see section Frame Font). Thus, if a window is displaying text with a different font or size, the reported line height and column width for that window may differ from the actual number of text lines or columns displayed within it.

The total height of a window is the number of lines comprising the window’s body, the header line, the horizontal scroll bar, the mode line and the bottom divider (if any).

Function: window-total-height &optional window round

この関数は、ウィンドウwindowのトータル高さを、行でリターンする。windowが省略、またはnilの場合のデフォルトは、選択されたウィンドウである。windowが内部ウィンドウの場合、リターン値はそのウィンドウの子孫となるウィンドウにより占有されるトータル高さになる。

If a window’s pixel height is not an integral multiple of its frame’s default character height, the number of lines occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total heights of all its child windows internally equals the total height of their parent. This means that although two windows have the same pixel height, their internal total heights may differ by one line. This means also, that if window is vertically combined and has a next sibling, the topmost row of that sibling can be calculated as the sum of this window’s topmost row and total height (see section 座標とウィンドウ)

オプション引数roundがceilingの場合、この関数はwindowのピクセル高さを、そのフレームの文字高さで除した数より大であるような最小の整数、floorの場合は除した数より小であるような最大の整数、それ以外のroundにたいしては、windowsのトータル高さの内部値をリターンする。

トータル幅(total width)とは、そのウィンドウのボディーを構成する列数、マージン、フリンジ、スクロールバー、(もしあれば)右ディバイダーです。

Function: window-total-width &optional window round

この関数は、ウィンドウwindowのトータル幅を列でリターンする。windowが省略、またはnilの場合のデフォルトは、選択されたウィンドウである。windowが内部ウィンドウの場合、リターン値はその子孫のウィンドウが占有するトータル幅になる。

If a window’s pixel width is not an integral multiple of its frame’s character width, the number of lines occupied by the window is rounded internally. This is done in a way such that, if the window is a parent window, the sum of the total widths of all its children internally equals the total width of their parent. This means that although two windows have the same pixel width, their internal total widths may differ by one column. This means also, that if this window is horizontally combined and has a next sibling, the leftmost column of that sibling can be calculated as the sum of this window’s leftmost column and total width (see section 座標とウィンドウ). The optional argument round behaves as it does for window-total-height.

Function: window-total-size &optional window horizontal round: この関数は、ウィンドウwindowのトータル高さを行で、またはトータル幅を列でリターンする。horizontalが省略、またはnilの場合はwindowにたいしてwindow-total-heightを呼び出すのと等価であり、それ以外ではwindowにたいしてwindow-total-widthを呼び出すのと等価である。オプション引数roundは、window-total-heightの場合と同様に振る舞う。

以下の2つの関数は、ウィンドウのトータルサイズをピクセル単位でリターンさせるために使用できます。

Function: window-pixel-height &optional window

この関数は、ウィンドウwindowのトータル高さを、ピクセルでリターンする。windowは有効なウィンドウでなければならず、デフォルトは選択されたウィンドウである。

The return value includes mode and header line, a horizontal scroll bar and a bottom divider, if any. If window is an internal window, its pixel height is the pixel height of the screen areas spanned by its children.

Function: window-pixel-height-before-size-change &optional Lisp_Object &optional window: This function returns the height of window window in pixels at the time window-size-change-functions was run for the last time on window’s frame (see section ウィンドウのスクロールと変更のためのフック).

Function: window-pixel-width &optional window

この関数は、ウィンドウwindowの幅をピクセルでリターンする。windowは有効なウィンドウでなければならず、デフォルトは選択されたウィンドウである。

リターン値には、フリンジ、windowのマージン、同様にwindowに属する垂直ディバイダーとスクロールバーが含まれる。windowが内部ウィンドウの場合、そのピクセル幅は子ウィンドウたちによりスパンされるスクリーン領域の幅になる。

Function: window-pixel-width-before-size-change &optional Lisp_Object &optional window: This function returns the width of window window in pixels at the time window-size-change-functions was run for the last time on window’s frame (see section ウィンドウのスクロールと変更のためのフック).

以下の関数は、与えられたウィンドウに隣接するウィンドウがあるかどうかを判断するために使用できます。

Function: window-full-height-p &optional window: This function returns non-nil if window has no other window above or below it in its frame. More precisely, this means that the total height of window equals the total height of the root window on that frame. The minibuffer window does not count in this regard. If window is omitted or nil, it defaults to the selected window.

Function: window-full-width-p &optional window: この関数は、フレーム内でwindowの左右に他のウィンドウがなければ非nilをリターンする(トータル幅がそのフレーム上のルートウィンドウと等しい)。windowが省略、またはnilの場合のデフォルトは、選択されたウィンドウである。

The body height of a window is the height of its text area, which does not include a mode or header line, a horizontal scroll bar, or a bottom divider.

Function: window-body-height &optional window pixelwise

この関数は、ウィンドウwindowのボディーの高さを、行でリターンする。windowが省略、またはnilの場合のデフォルトは選択されたウィンドウで、それ以外では生きたウィンドウでなければならない。

オプション引数pixelwiseが非nilの場合、この関数はピクセルで計算windowのボディー高さをリターンする。

pixelwiseがnilの場合は、必要ならリターン値はもっとも近い整数に切り下げられる。これは、テキスト領域の下端行が部分的に可視の場合、その行は計数されないこと、さらに任意のウィンドウのボディー高さは、window-total-heightによりリターンされるそのウィンドウのトータル高さ決して超過し得ないことをも意味する。

The body width of a window is the width of its text area, which does not include the scroll bar, fringes, margins or a right divider. Note that when one or both fringes are removed (by setting their width to zero), the display engine reserves two character cells, one on each side of the window, for displaying the continuation and truncation glyphs, which leaves 2 columns less for text display. (The function window-max-chars-per-line, described below, takes this peculiarity into account.)

Function: window-body-width &optional window pixelwise

この関数は、ウィンドウwindowのボディーの幅を、列でリターンする。windowが省略、またはnilの場合のデフォルトは選択されたウィンドウであり、それ以外では生きたウィンドウでなければならない

オプション引数pixelwiseが非nilの場合、この関数はwindowのボディーの幅をピクセル単位でリターンする。

pixelwiseがnilの場合、リターン値は必要ならもっとも近い整数に切り下げられる。これはテキスト領域の右端の列が部分的に可視な場合は、その列は計数されないことを意味する。さらにこれは、ウィンドウのボディーの幅が、window-total-widthによりリターンされるウィンドウのトータル幅を決して超過し得ないことをも意味する。

Function: window-body-size &optional window horizontal pixelwise: この関数は、windowのボディーの高さ、または幅をリターンする。horizontalが省略、またはnilの場合は、windowにたいしてwindow-body-height、それ以外の場合は、window-body-widthを呼び出すのと同じである。いずれの場合も、オプション引数pixelwiseは、呼び出された関数に渡される。

以前のバージョンのEmacsとの互換性のため、window-heightはwindow-total-height、window-widthはwindow-body-widthにたいするエイリアスです。これらのエイリアス時代遅れと考えられております、将来的には削除されるでしょう。

ウィンドウのモードラインとヘッダーラインのピクセル高さは、以下の関数により取得できる。それらのリターン値は、そのウィンドウが以前に表示されていない場合を除き、通常は加算される。その場合、リターン値はそのウィンドウのフレームにたいして使用を予想されるフォントが元になる。

Function: window-mode-line-height &optional window: この関数は、windowモードラインの高さをピクセルでリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。windowにモードラインがない場合、リターン値は0である。

Function: window-header-line-height &optional window: この関数は、windowのヘッダーラインの高さをピクセルでリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。windowにヘッダーラインがない場合のリターン値は0である。

ウィンドウディバイダー(ウィンドウディバイダーを参照)、フリンジ(フリンジを参照)、スクロールバー(スクロールバーを参照)、ディスプレイマージン(マージン内への表示を参照)を取得する関数については、対応するセクションで説明されています。

If your Lisp program needs to make layout decisions, you will find the following function useful:

Function: window-max-chars-per-line &optional window face

This function returns the number of characters displayed in the specified face face in the specified window window (which must be a live window). If face was remapped (see section フェイスのリマップ), the information is returned for the remapped face. If omitted or nil, face defaults to the default face, and window defaults to the selected window.

Unlike window-body-width, this function accounts for the actual size of face’s font, instead of working in units of the canonical character width of window’s frame (see section Frame Font). It also accounts for space used by the continuation glyph, if window lacks one or both of its fringes.

Commands that change the size of windows (see section ウィンドウのリサイズ), or split them (see section ウィンドウの分割), obey the variables window-min-height and window-min-width, which specify the smallest allowable window height and width. They also obey the variable window-size-fixed, with which a window can be fixed in size (see section Preserving Window Sizes).

User Option: window-min-height: This option specifies the minimum total height, in lines, of any window. Its value has to accommodate at least one text line as well as a mode and header line, a horizontal scroll bar and a bottom divider, if present.

User Option: window-min-width: このオプションは、すべてのウィンドウの最小のトータル幅を列で指定する。この値は、2つのテキスト列、同様に(もしあれば)マージン、フリンジ、スクロールバー、右ディバイダーに対応する必要がある。

The following function tells how small a specific window can get taking into account the sizes of its areas and the values of window-min-height, window-min-width and window-size-fixed (see section Preserving Window Sizes).

Function: window-min-size &optional window horizontal ignore pixelwise

この関数は、windowの最小のサイズをリターンする。windowは有効なウィンドウでなければならず、デフォルトは選択されたウィンドウ。オプション引数horizontalが非nilの場合は、windowの最小の列数、それ以外はwindowの最小の行数をリターンすることを意味する。

The return value makes sure that all components of window remain fully visible if window’s size were actually set to it. With horizontal nil it includes the mode and header line, the horizontal scroll bar and the bottom divider, if present. With horizontal non-nil it includes the margins and fringes, the vertical scroll bar and the right divider, if present.

オプション引数ignoreが非nilの場合は、window-min-heightまたはwindow-min-widthによりセットされる固定サイズのウィンドウに強いられる制限を無視することを意味する。ignoreがsafeの場合は、生きたウィンドウは可能な限り小さなwindow-safe-min-heightの行と、window-safe-min-widthの列を得る。ignoreにウィンドウが指定された場合は、そのウィンドウにたいする制限だけを無視する。その他の非nil値では、すべてのウィンドウにたいする上記制限のすべてが無視されることを意味する。

オプション引数pixelwiseが非nilの場合は、windowの最小サイズがピクセルで計数されてリターンされることを意味する。

28.4 ウィンドウのリサイズ

This section describes functions for resizing a window without changing the size of its frame. Because live windows do not overlap, these functions are meaningful only on frames that contain two or more windows: resizing a window also changes the size of a neighboring window. If there is just one window on a frame, its size cannot be changed except by resizing the frame (see section Frame Size).

注記した場合を除き、これらの関数は引数として内部ウィンドウも受け付けます。内部ウィンドウのリサイズにより、同じスペースにフィットするよう、子ウィンドウもリサイズされます。

Function: window-resizable window delta &optional horizontal ignore pixelwise

この関数は、windowのサイズがdelta行により垂直に変更され得る場合は、deltaをリターンする。オプション引数horizontalが非nilの場合は、windowがdelta列単位に水平方向にリサイズ可能ならば、かわりにdeltaをリターンする。これは、実際にはウィンドウのサイズを変更しない。

windowがnilの場合のデフォルトは選択されたウィンドウ。

deltaが正の値の場合は、そのウィンドウが行または列の単位で拡張可能かどうかをチェックすることを意味し、deltaが負の値の場合は、そのウィンドウが行または列の単位で縮小可能かどうかをチェックすることを意味する。deltaが非0の場合のリターン値0は、そのウィンドウがリサイズ可能であることを意味する。

Normally, the variables window-min-height and window-min-width specify the smallest allowable window size (see section ウィンドウのサイズ). However, if the optional argument ignore is non-nil, this function ignores window-min-height and window-min-width, as well as window-size-fixed. Instead, it considers the minimum-height window to be one consisting of a header and a mode line, a horizontal scrollbar and a bottom divider (if any), plus a text area one line tall; and a minimum-width window as one consisting of fringes, margins, a scroll bar and a right divider (if any), plus a text area two columns wide.

オプション引数pixelwiseが非nilの場合、deltaはピクセル単位として解釈される。

Function: window-resize window delta &optional horizontal ignore pixelwise

この関数は、windowをdelta増加することによりリサイズする。horizontalがnilの場合は高さをdelta行、それ以外は幅をdelta行変更する。正のdeltaはウィンドウの拡大、負のdeltaは縮小を意味する。

windowがnilの場合のデフォルトは、選択されたウィンドウである。要求されたようにウィンドウをリサイズできない場合は、エラーをシグナルする。

オプション引数ignoreは、上述の関数window-resizableの場合と同じ意味をもつ。

オプション引数pixelwiseが非nilの場合、deltaはピクセル単位として解釈される。

この関数はどのウィンドウのエッジを変更するかの選択は、オプションwindow-combination-resizeの値と、関連するウィンドウのコンビネーションリミット(combination limits: 組み合わせ制限)に依存し、両方のエッジを変更するような場合もいくつかある。ウィンドウの再結合を参照のこと。ウィンドウの下端または右端のエッジを移動することだけでリサイズするには、関数adjust-window-trailing-edgeを使用すること。

Function: adjust-window-trailing-edge window delta &optional horizontal pixelwise

この関数は、windowの下端エッジをdelta行分移動する。オプション引数horizontalが非nilの場合は、かわりに右端エッジをdelta列分移動する。windowがnilの場合のデフォルトは、選択されたウィンドウである。

オプション引数pixelwiseが非nilの場合、deltaはピクセル単位として解釈される。

A positive delta moves the edge downwards or to the right; a negative delta moves it upwards or to the left. If the edge cannot be moved as far as specified by delta, this function moves it as far as possible but does not signal an error.

この関数は、移動されたエッジに隣接するウィンドウのリサイズを試みる。何らかの理由(隣接するウィンドウが固定サイズの場合等)により、それが不可能な場合は、他のウィンドウをリサイズするかもしれない。

User Option: window-resize-pixelwise

If the value of this option is non-nil, Emacs resizes windows in units of pixels. This currently affects functions like split-window (see section ウィンドウの分割), maximize-window, minimize-window, fit-window-to-buffer, fit-frame-to-buffer and shrink-window-if-larger-than-buffer (all listed below).

あるフレームのピクセルサイズがそのフレームの文字サイズの整数倍でないときは、たとえこのオプションがnilであっても、少なくとも1つのウィンドウがピクセル単位でリサイズされるであろうことに注意されたい。デフォルト値はnilである。

以下のコマンドは、より具体的な方法でウィンドウをリサイズします。これらがインタラクティブに呼び出されたときは、選択されたウィンドウにたいして作用します。

Command: fit-window-to-buffer &optional window max-height min-height max-width min-width preserve-size

このコマンドは、windowの高さまたは幅を、ウィンドウ内のテキストにフィットするように調整する。windowがリサイズできた場合は非nil、それ以外はnilをリターンする。windowが省略またはnilの場合のデフォルトは選択されたウィンドウ、それ以外の場合は生きたウィンドウであること。

windowが垂直コンビネーションの一部の場合、この関数はwindowの高さを調整する。新たな高さは、そのウィンドウのバッファーのアクセス可能な範囲の実際の高さから計算される。オプション引数max-heightが非nilの場合、それはこの関数がwindowに与えることができる、最大のトータル高さを指定する。オプション引数min-heightが非nilの場合、それは与えることができる最小のトータル高さを指定し、それは変数window-min-heightをオーバーライドする。max-heightとmin-heightはどちらも、(もしあれば)モードライン、ヘッダーライン、下端ディバイダーを含む行数で指定する。

If window is part of a horizontal combination and the value of the option fit-window-to-buffer-horizontally (see below) is non-nil, this function adjusts window’s width. The new width of window is calculated from the maximum length of its buffer’s lines that follow the current start position of window. The optional argument max-width specifies a maximum width and defaults to the width of window’s frame. The optional argument min-width specifies a minimum width and defaults to window-min-width. Both max-width and min-width are specified in columns and include fringes, margins and scrollbars, if any.

The optional argument preserve-size, if non-nil, will install a parameter to preserve the size of window during future resize operations (see section Preserving Window Sizes).

If the option fit-frame-to-buffer (see below) is non-nil, this function will try to resize the frame of window to fit its contents by calling fit-frame-to-buffer (see below).

User Option: fit-window-to-buffer-horizontally: これが非nilの場合、fit-window-to-bufferはウィンドウを水平方向にリサイズできる。これがnil(デフォルト)の場合、fit-window-to-bufferはウィンドウウィンドウ決して水平方向にリサイズしない。これがonlyの場合は、ウィンドウを水平方向だけにリサイズできる。その他の値では、fit-window-to-bufferがウィンドウをどちらの方向にもリサイズできることを意味する。

User Option: fit-frame-to-buffer: このオプションが非nilの場合、fit-window-to-bufferはフレームをフレームのコンテンツにフィットさせることができる。フレームは、フレームのルートウィンドウが生きたウィンドウで、かつこのオプションが非nilの場合のみ、フィットされる。これがhorizontallyの場合、フレームは水平方向にのみフィットされる。これがverticallyの場合、フレームは垂直方向にのみフィットされる。その他の非nil値は、フレームがどちらの方向にもフィットできることを意味する。

If you have a frame that displays only one window, you can fit that frame to its buffer using the command fit-frame-to-buffer.

Command: fit-frame-to-buffer &optional frame max-height min-height max-width min-width only

This command adjusts the size of frame to display the contents of its buffer exactly. frame can be any live frame and defaults to the selected one. Fitting is done only if frame’s root window is live. The arguments max-height, min-height, max-width and min-width specify bounds on the new total size of frame’s root window. min-height and min-width default to the values of window-min-height and window-min-width respectively.

If the optional argument only is vertically, this function may resize the frame vertically only. If only is horizontally, it may resize the frame horizontally only.

The behavior of fit-frame-to-buffer can be controlled with the help of the two options listed next.

User Option: fit-frame-to-buffer-margins

This option can be used to specify margins around frames to be fit by fit-frame-to-buffer. Such margins can be useful to avoid, for example, that the resized frame overlaps the taskbar or parts of its parent frame.

It specifies the numbers of pixels to be left free on the left, above, the right, and below a frame that shall be fit. The default specifies nil for each which means to use no margins. The value specified here can be overridden for a specific frame by that frame’s fit-frame-to-buffer-margins parameter, if present.

User Option: fit-frame-to-buffer-sizes: This option specifies size boundaries for fit-frame-to-buffer. It specifies the total maximum and minimum lines and maximum and minimum columns of the root window of any frame that shall be fit to its buffer. If any of these values is non-nil, it overrides the corresponding argument of fit-frame-to-buffer.

Command: shrink-window-if-larger-than-buffer &optional window

このコマンドは、windowにたいしてそのバッファーを完全に表示できるが、window-min-height以上の行を表示できるまで、可能な限りwindowの高さを縮小する。リターン値は、そのウィンドウがリサイズされれば非nil、それ以外は非nil。windowが省略またはnilの場合のデフォルトは、選択されたウィンドウである。それ以外では、生きたウィンドウであること。

このコマンドは、そのウィンドウがバッファーのすべてを表示するにはすでに高さが低すぎる場合、バッファーのどこかがスクリーンからスクロールオフされている場合、またはそのウィンドウがフレーム内で唯一の生きたウィンドウの場合は何も行わない。

このコマンドは、自身の処理を行うために、fit-window-to-buffer(上記参照)を呼び出す。

Command: balance-windows &optional window-or-frame: この関数は、各ウィンドウにたいして完全な幅、および/または完全な高さを与えるような方法により、各ウィンドウのバランスをとる。window-or-frameにフレームを指定した場合は、そのフレーム上のすべてのウィンドウのバランスをとる。window-or-frameにウィンドウを指定した場合は、そのウィンドウとウィンドウのsiblings(兄弟)にたいしてのみのバランスをとる(ウィンドウとフレームを参照)。

Command: balance-windows-area: この関数は、選択されたフレーム上のすべてのウィンドウにたいして、おおよそ同じスクリーンエリアを与えようと試みる。完全な幅、または高さをもつウィンドウにたいしては、他のウィンドウと比較して、より多くのスペースは与えられない。

Command: maximize-window &optional window: この関数は、windowにたいして、そのフレームをリサイズしたり、他のウィンドウを削除することなく、水平垂直の両方向において、可能な限り大きくなるように試みる。windowが省略またはnilの場合のデフォルトは、選択されたウィンドウである。

Command: minimize-window &optional window: この関数は、windowにたいして、そのフレームをリサイズしたり、そのウィンドウを削除することなく、水平垂直の両方向において、可能な限り小さくなるように試みる。windowが省略またはnilの場合のデフォルトは、選択されたウィンドウである。

28.5 Preserving Window Sizes

A window can get resized explicitly by using one of the functions from the preceding section or implicitly, for example, when resizing an adjacent window, when splitting or deleting a window (see section ウィンドウの分割, see section ウィンドウの削除) or when resizing the window’s frame (see section Frame Size).

It is possible to avoid implicit resizing of a specific window when there are one or more other resizable windows on the same frame. For this purpose, Emacs must be advised to preserve the size of that window. There are two basic ways to do that.

Variable: window-size-fixed

If this buffer-local variable is non-nil, the size of any window displaying the buffer cannot normally be changed. Deleting a window or changing the frame’s size may still change the window’s size, if there is no choice.

値がheightの場合は、そのウィンドウの高さだけが固定される。値がwidthの場合は、そのウィンドウの幅だけが固定される。その他の非nil値では、幅と高さの両方が固定される。

この変数がnil場合でも、そのバッファーを表示している任意のウィンドウを任意の方向にリサイズできるとはいえない。これを決定するには、関数window-resizableを使用する。ウィンドウのリサイズを参照のこと。

Often window-size-fixed is overly aggressive because it inhibits any attempt to explicitly resize or split an affected window as well. This may even happen after the window has been resized implicitly, for example, when deleting an adjacent window or resizing the window’s frame. The following function tries hard to never disallow resizing such a window explicitly:

Function: window-preserve-size &optional window horizontal preserve

This function (un-)marks the height of window window as preserved for future resize operations. window must be a live window and defaults to the selected one. If the optional argument horizontal is non-nil, it (un-)marks the width of window as preserved.

If the optional argument preserve is t, this means to preserve the current height/width of window’s body. The height/width of window will change only if Emacs has no better choice. Resizing a window whose height/width is preserved by this function never throws an error.

If preserve is nil, this means to stop preserving the height/width of window, lifting any respective restraint induced by a previous call of this function for window. Calling enlarge-window, shrink-window or fit-window-to-buffer with window as argument may also remove the respective restraint.

window-preserve-size is currently invoked by the following functions:

fit-window-to-buffer: If the optional argument preserve-size of that function (see section ウィンドウのリサイズ) is non-nil, the size established by that function is preserved.
display-buffer: If the alist argument of that function (see section 表示するウィンドウの選択) contains a preserve-size entry, the size of the window produced by that function is preserved.

window-preserve-size installs a window parameter (see section ウィンドウのパラメーター) called window-preserved-size which is consulted by the window resizing functions. This parameter will not prevent resizing the window when the window shows another buffer than the one when window-preserve-size was invoked or if its size has changed since then.

The following function can be used to check whether the height of a particular window is preserved:

Function: window-preserved-size &optional window horizontal: This function returns the preserved height of window window in pixels. window must be a live window and defaults to the selected one. If the optional argument horizontal is non-nil, it returns the preserved width of window. It returns nil if the size of window is not preserved.

28.6 ウィンドウの分割

This section describes functions for creating a new window by splitting an existing one. Note that some windows are special in the sense that these functions may fail to split them as described here. Examples of such windows are side windows (see section Side Windows) and atomic windows (see section Atomic Windows).

Function: split-window &optional window size side pixelwise

This function creates a new live window next to the window window. If window is omitted or nil, it defaults to the selected window. That window is split, and reduced in size. The space is taken up by the new window, which is returned.

オプションの第2引数sizeは、windowおよび/または新たなウィンドウのサイズを決定する。これが省略またはnilの場合は、両方のウィンドウに同じサイズが割り当てられる。行数が奇数の場合、余りの1行は新たなウィンドウに割り当てられる。sizeが正の数値の場合、windowにsizeの行数(sideの値によっては列数)が与えられる。sizeが負の数値の場合、新たなウィンドウに-sizeの行数(または列数)が与えられる。

sizeがnilの場合、この関数は変数window-min-heightとwindow-min-widthにしたがう(ウィンドウのサイズを参照)。つまり、分割によりこれらの変数の指定より小さいウィンドウが作成されるようなときは、エラーをシグナルする。しかし、sizeにたいして非nil値を指定すれば、これらの変数は無視される。その場合、許容される最小のウィンドウは、テキストエリアの高さが1行、および/または幅が2列のウィンドウであるとされる。

Hence, if size is specified, it’s the caller’s responsibility to check whether the emanating windows are large enough to encompass all areas like a mode line or a scroll bar. The function window-min-size (see section ウィンドウのサイズ) can be used to determine the minimum requirements of window in this regard. Since the new window usually inherits areas like the mode line or the scroll bar from window, that function is also a good guess for the minimum size of the new window. The caller should specify a smaller size only if it correspondingly removes an inherited area before the next redisplay.

オプションの第3引数sideは、新たなウィンドウの位置をwindowから相対的に指定する。nilまたはbelowの場合、新たなウィンドウはwindowの下に、aboveの場合はwindowの上に配される。どちらの場合も、sizeはウィンドウのトータル高さを行数で指定する。

sideがtまたはrightの場合、新たなウィンドウはwindowの右に、sideがleftの場合はwindowの左に配される。どちらの場合も、sizeはウィンドウのトータル幅を列数で指定する。

オプションの第4引数pixelwiseが非nilの場合は、sizeを行や列ではなくピクセル単位で解釈することを意味する。

windowが生きたウィンドウの場合、新たなウィンドウはマージンやスクロールバーを含む、さまざまなプロパティを継承する。windowが内部ウィンドウ(internal window)の場合、新たなウィンドウはwindowのフレームのプロパティを継承する。

変数ignore-window-parametersがnilの場合に限り、この関数の挙動はwindowなパラメーターにより変更されるかもしれない。ウィンドウパラメーターsplit-windowの値がtの場合、この関数はその他すべてのウィンドウパラメーターを無視する。それ以外では、ウィンドウパラメーターsplit-windowの値が関数の場合は、split-windowの通常アクションのかわりに、引数window、size、sideでその関数が呼び出される。値が関数以外の場合、この関数は(もしあれば)ウィンドウパラメーターwindow-atomまたはwindow-sideにしたがう。ウィンドウのパラメーターを参照のこと。

例として、ウィンドウとフレームで議論したウィンドウ構成(window configuration)を得るための、一連のsplit-window呼び出しを以下に挙げます。この例では、生きたウィンドウの分割と、内部ウィンドウの分割も示します。最初はW4で表される、単一のウィンドウ(生きたルートウィンドウ)を含むフレームから開始します。(split-window W4)を呼び出すことにより、以下のウィンドウ構成が得られます。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W5_________________||
    |__________________W3__________________|

split-window呼び出しにより、W5で示す生きたウィンドウが新たに作成されました。W3で示される内部ウィンドウも新たに作成され、これはルートウィンドウかつW4とW5の親ウィンドウになります。

次は、引数として内部ウィンドウW3を渡して、(split-window W3 nil 'left)を呼び出します。

     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

内部ウィンドウW3の左に、生きたウィンドウW2が新たに作成されました。そして、内部ウィンドウW1が新たに作成され、これが新たにルートウィンドウになります。

インタラクティブな使用にたいして、Emacsは選択されたウィンドウを常に分割するコマンドを2つ提供します。これらは内部でsplit-windowを呼び出します。

Command: split-window-right &optional size: この関数は、選択されたウィンドウが左となるような、横並びの2つのウィンドウに分割する。sizeが正ならば左のウィンドウがsize列、負ならば右のウィンドウが-size列を与えられる。

Command: split-window-below &optional size: この関数は、選択されたウィンドウが上となるような、縦並びの2つのウィンドウに分割する。sizeが正ならば上のウィンドウがsize行、負ならば下のウィンドウが-size行を与えられる。

User Option: split-window-keep-point

この変数の値が非nil(デフォルト)なら、 split-window-belowは上述のように振る舞う。

nilの場合、split-window-belowは再表示が最小となるように、2つのウィンドウの各ポイントを調節する(これは低速な端末で有用である)。これは何であれ、以前ポイントがあったスクリーン行(screen line)を含むウィンドウを選択する。これは低レベルsplit-window関数ではなく、split-window-belowだけに影響することに注意。

28.7 ウィンドウの削除

ウィンドウを削除(delete)することにより、フレームのウィンドウツリーからウィンドウが取り除かれます。それが生きたウィンドウの場合は、スクリーンに表示されなくなります。内部ウィンドウの場合は、その子ウィンドウも削除されます。

ウィンドウを削除した後でも、それへの参照が残っている限り、Lispオブジェクトとして存在し続けます。ウィンドウ構成(window configuration)をリストアすることにより、ウィンドウの削除は取り消すことができます(ウィンドウの構成を参照)。

Command: delete-window &optional window

This function removes window from display and returns nil. If window is omitted or nil, it defaults to the selected window.

If deleting the window would leave no more windows in the window tree (e.g., if it is the only live window in the frame) or all remaining windows on window’s frame are side windows (see section Side Windows), an error is signaled.

By default, the space taken up by window is given to one of its adjacent sibling windows, if any. However, if the variable window-combination-resize is non-nil, the space is proportionally distributed among any remaining windows in the same window combination. See section ウィンドウの再結合.

The behavior of this function may be altered by the window parameters of window, so long as the variable ignore-window-parameters is nil. If the value of the delete-window window parameter is t, this function ignores all other window parameters. Otherwise, if the value of the delete-window window parameter is a function, that function is called with the argument window, in lieu of the usual action of delete-window. See section ウィンドウのパラメーター.

Command: delete-other-windows &optional window

This function makes window fill its frame, deleting other windows as necessary. If window is omitted or nil, it defaults to the selected window. An error is signaled if window is a side window (see section Side Windows). The return value is nil.

The behavior of this function may be altered by the window parameters of window, so long as the variable ignore-window-parameters is nil. If the value of the delete-other-windows window parameter is t, this function ignores all other window parameters. Otherwise, if the value of the delete-other-windows window parameter is a function, that function is called with the argument window, in lieu of the usual action of delete-other-windows. See section ウィンドウのパラメーター.

Also, if ignore-window-parameters is nil, this function does not delete any window whose no-delete-other-windows parameter is non-nil.

Command: delete-windows-on &optional buffer-or-name frame

この関数は、buffer-or-nameを表示しているすべてのウィンドウにたいしてdelete-windowを呼び出すことにより、それらを削除する。buffer-or-nameはバッファー、またはバッファー名であること。省略またはnilの場合のデフォルトはカレントバッファーである。指定されたバッファーを表示するウィンドウが存在しない場合、この関数は何も行わない。ミニバッファーが指定された場合は、エラーをシグナルする。

そのバッファーの表示に専用(dedicated)のウィンドウがあり、フレーム上でそれが唯一のウィンドウの場合、それが端末上で唯一のフレームでなければ、この関数はそのフレームも削除する。

オプション引数frameは、操作を行うフレームがどれかを指定する:

nil すべてのフレームを処理することを意味する。
t 選択されたフレームを処理することを意味する。
visible 可視なすべてのフレームを処理することを意味する。
0 可視またはアイコン化されたすべてのフレームを処理することを意味する。
フレームそのフレームを処理することを意味する。

この引数の意味は、すべての生きたウィンドウを走査する他の関数(ウィンドウのサイクル順を参照)における場合とは異なることに注意。特に、ここでのtとnilのもつ意味は、これら他の関数の場合とは逆である。

28.8 ウィンドウの再結合

ウィンドウWの最後の兄弟を削除したときは、ウィンドウツリー内の親ウィンドウをWを置き換えることにより、その親ウィンドウも削除されます。これは、新たなウィンドウコンビネーションを形成するために、Wがその親の兄弟たちと再結合されなければならないことを意味します。生きたウィンドウを削除することにより、必然的に2つの内部ウィンドウが削除されるかもしれない場合もあります。

     ______________________________________
    | ______  ____________________________ |
    ||      || __________________________ ||
    ||      ||| ___________  ___________ |||
    ||      ||||           ||           ||||
    ||      ||||____W6_____||_____W7____||||
    ||      |||____________W4____________|||
    ||      || __________________________ ||
    ||      |||                          |||
    ||      |||                          |||
    ||      |||____________W5____________|||
    ||__W2__||_____________W3_____________ |
    |__________________W1__________________|

この構成におけるW5の削除は、通常はW3とW4の削除を引き起こします。残りの生きたウィンドウW2、W6、W7は親をW7とする水平コンビネーションを形成するために再結合されます。

しかし、ときにはW4のような親ウィンドウを削除しないほうが合理的な場合もあります。特に、親ウィンドウが同じタイプのコンビネーション内に埋め込まれるコンビネーションを保護するために使用されるときは、それを削除するべきではありません。そのような埋め込みは、あるウィンドウを分割した後に続けて新たなウィンドウを削除する際、Emacsが関連するフレームで分割前にあったレイアウトを確実に再確立するために意味があります。

親がW1であるような2つの生きたウィンドウW2とW3を開始点とするシナリオを考えてみましょう。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

W2を分割すると、以下のようにウィンドウW4が新たに作成されます。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

ここでウィンドウを垂直方向に拡大すると、Emacsはもしそのようなウィンドウがあれば、下位の兄弟ウィンドウから対応するスペースを得ようと試みます。このシナリオでふぁW4の拡大により、W3からスペースが奪われます。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    | ____________________________________ |
    ||_________________W3_________________||
    |__________________W1__________________|

W4を削除すると、前にW3から奪ったスペースを含む、スペース全体がW2に与えられるでしょう。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||_________________W3_________________||
    |__________________W1__________________|

これは特にW4が一時的にバッファーを表示するために使用されていて(一時的な表示を参照)、かつ初期のレイアウトで作業を継続したい場合は直感に反するかもしれません。

The behavior can be fixed by making a new parent window when splitting W2. The variable described next allows that to be done.

User Option: window-combination-limit

この変数は、ウィンドウ分割により新たに親ウィンドウを作成させるかどうかを制御する。以下の値が認識される:

nil: これは、既存のウィンドウコンビネーションと同じ方向で分割が発生した場合(これ以外の場合は、いずれにせよ内部ウィンドウが新たに作成される)は、既存の親ウィンドウが存在するならば、新たな生きたウィンドウがそれを共有できることを意味する。
window-size: This means that display-buffer makes a new parent window when it splits a window and is passed a window-height or window-width entry in the alist argument (see section display-bufferにたいするアクション関数). Otherwise, window splitting behaves as for a value of nil.
temp-buffer-resize: In this case with-temp-buffer-window makes a new parent window when it splits a window and temp-buffer-resize-mode is enabled (see section 一時的な表示). Otherwise, window splitting behaves as for nil.
temp-buffer: In this case with-temp-buffer-window always makes a new parent window when it splits an existing window (see section 一時的な表示). Otherwise, window splitting behaves as for nil.
display-buffer: This means that when display-buffer (see section 表示するウィンドウの選択) splits a window it always makes a new parent window. Otherwise, window splitting behaves as for nil.
t: This means that splitting a window always creates a new parent window. Thus, if the value of this variable is at all times t, then at all times every window tree is a binary tree (a tree where each window except the root window has exactly one sibling).

The default is window-size. Other values are reserved for future use.

この返信のセッティングの結果としてsplit-windowが新たに親ウィンドウを作成した場合は、新たに作成された内部ウィンドウにたいしてset-window-combination-limit(以下参照)も呼び出す。これは、子ウィンドウが削除された際の、ウィンドウツリーの再配置に影響する(以下参照)。

window-combination-limitがtの場合、このシナリオの初期構成では以下のようになるでしょう:

     ______________________________________
    | ____________________________________ |
    || __________________________________ ||
    |||                                  |||
    |||________________W2________________|||
    || __________________________________ ||
    |||                                  |||
    |||________________W4________________|||
    ||_________________W5_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

子としてW2および新たな生きたウィンドウをもつ内部ウィンドウW5が新たに作成されます。ここでW2はW4の唯一の兄弟なので、W4を拡大するとW3は変更せずに、W2を縮小しようと試みるでしょう。W5は垂直コンビネーションW1に埋め込まれた、2つのウィンドウからなる垂直コンビネーションを表すことに注意してください。

Function: set-window-combination-limit window limit: この関数は、ウィンドウwindowのコンビネーションリミット(combination limit: 結合限界をlimitにセットする。この値は、関数window-combination-limitを通じて取得できる。効果については以下を参照のこと。これは内部ウィンドウにたいしてのみ意味をもつことに注意されたい。split-windowは、呼び出された際に変数window-combination-limitがtならば、tをlimitとして、この関数を呼び出す。

Function: window-combination-limit window

この関数は、windowにたいするコンビネーションリミットをリターンする。

コンビネーションリミットは、内部ウィンドウにたいしてのみ意味をもつ。これがnilの場合は、Emacsはウィンドウ削除に応じて、兄弟同士で新たなウィンドウコンビネーションを形成することにより、windowの子ウィンドウをグループ化するために、windowの自動的な削除を許す。コンビネーションリミットがtの場合、windowの子ウィンドウは、その兄弟と自動的に再結合されることは決してない。

このセクションの冒頭で示した構成の場合、W4(W6とW7の親ウィンドウ)のコンビネーションリミットはtなので、tを削除しても暗黙でW4も削除されることはない。

Alternatively, the problems sketched above can be avoided by always resizing all windows in the same combination whenever one of its windows is split or deleted. This also permits splitting windows that would be otherwise too small for such an operation.

User Option: window-combination-resize

この変数がnilの場合、split-windowはウィンドウ(以下window)自身と新たなウィンドウの両方にたいして、windowのスクリーンエリアが十分大きい場合のみ、windowを分割できる。

この変数がtの場合、split-windowは新たなウィンドウに対応するため、windowと同じコンビネーション内の、すべてのウィンドウのリサイズを試みる。これは特に、windowが固定サイズウィンドウのときや、通常の分割には小さすぎるときも、split-windowをが成功することを許す。さらに、続けてwindowをリサイズ、または削除すると、そのコンビネーション内のその他すべてのウィンドウをリサイズする。

The default is nil. Other values are reserved for future use. A specific split operation may ignore the value of this variable if it is affected by a non-nil value of window-combination-limit.

window-combination-resizeの効果を説明するために、以下のフレームレイアウトを考えてください。

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    |__________________W1__________________|

window-combination-resizeがnilの場合、ウィンドウW3を分割しても、W2のサイズは変更されません:

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

window-combination-resizeがtの場合は、W3を分割すると3つの生きたウィンドウすべてを、おおよそ同じ高さにします:

     ______________________________________
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W2_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W3_________________||
    | ____________________________________ |
    ||                                    ||
    ||                                    ||
    ||_________________W4_________________||
    |__________________W1__________________|

生きたウィンドウW2、W3、W4のいずれを削除しても、削除されたウィンドウのスペースは、残りの2つの生きたウィンドウに相対的に分配されます。

28.9 ウィンドウの選択

Function: select-window window &optional norecord

This function makes window the selected window and the window selected within its frame (see section Emacsウィンドウの基本概念), and selects that frame. It also makes window’s buffer (see section バッファーとウィンドウ) current and sets that buffer’s value of point to the value of window-point (see section ウィンドウとポイント) in window. window must be a live window. The return value is window.

By default, this function also moves window’s buffer to the front of the buffer list (see section バッファーリスト) and makes window the most recently selected window. If the optional argument norecord is non-nil, these additional actions are omitted.

In addition, this function by default also tells the display engine to update the display of window when its frame gets redisplayed the next time. If norecord is non-nil, such updates are usually not performed. If, however, norecord equals the special symbol mark-for-redisplay, the additional actions mentioned above are omitted but window will be nevertheless updated.

Note that sometimes selecting a window is not enough to show it, or make its frame the top-most frame on display: you may also need to raise the frame or make sure input focus is directed to that frame. See section 入力のフォーカス.

For historical reasons, Emacs does not run a separate hook whenever a window gets selected. Applications and internal routines often temporarily select a window to perform a few actions on it. They do that either to simplify coding—because many functions by default operate on the selected window when no window argument is specified—or because some functions did not (and still do not) take a window as argument and always operate(d) on the selected window instead. Running a hook every time a window gets selected for a short time and once more when the previously selected window gets restored is not useful.

However, when its norecord argument is nil, select-window updates the buffer list and thus indirectly runs the normal hook buffer-list-update-hook (see section バッファーリスト). Consequently, that hook provides a reasonable way to run a function whenever a window gets selected more “permanently”.

Since buffer-list-update-hook is also run by functions that are not related to window management, it will usually make sense to save the value of the selected window somewhere and compare it with the value of selected-window while running that hook. Also, to avoid false positives when using buffer-list-update-hook, it is good practice that every select-window call supposed to select a window only temporarily passes a non-nil norecord argument. If possible, the macro with-selected-window (see below) should be used in such cases.

引数norecordに非nilを指定したselect-windowの連続呼び出しは、ウィンドウの並び順を選択時刻により決定します。関数get-lru-windowは、もっとも昔に選択された生きたウィンドウ(ウィンドウのサイクル順を参照)を取得するために使用できます。

Macro: save-selected-window forms…

このマクロは、選択されたフレーム、同様に各フレームの選択されたウィンドウを記録し、formsを順に実行してから、以前に選択されていたフレームとウィンドウをリストアする。これはカレントバッファーの保存とリストアも行う。リターン値はforms内の最後のフォームの値である。

このマクロは、ウィンドウのサイズ、コンテンツ、配置についての保存やリストアは何も行わない。したがって、formsがそれらを変更した場合、その変更は永続化される。あるフレームにおいて以前に選択されていたウィンドウがformsのexit時にもはや生きていない場合、そのフレームの選択されたウィンドウはそのまま放置される。以前に選択されていたウィンドウがもはや生きていない場合はformsの最後に選択されていたウィンドウが何であれ、それが選択されたままになる。カレントバッファーformsのexit時にそれが生きている場合のみリストアされる。

このマクロは、もっとも最近に選択されたウィンドウとバッファーリストの順番を、どちらも変更しない。

Macro: with-selected-window window forms…: This macro selects window, executes forms in sequence, then restores the previously selected window and current buffer. The ordering of recently selected windows and the buffer list remain unchanged unless you deliberately change them within forms; for example, by calling select-window with argument norecord nil. Hence, this macro is the preferred way to temporarily work with window as the selected window without needlessly running buffer-list-update-hook.

Function: frame-selected-window &optional frame: この関数は、フレームframe内で選択されているウィンドウをリターンする。frameは生きたフレームであること。省略またはnilの場合のデフォルトは、選択されたフレームである。

Function: set-frame-selected-window frame window &optional norecord

この関数は、windowをフレームframe内で選択されたウィンドウにする。frameは生きたフレームであること。省略またはnilの場合のデフォルトは、選択されたフレームである。windowは生きたウィンドウであること。省略またはnilの場合のデフォルトは選択されたウィンドウである。

frameが選択されたフレームの場合は、windowを選択されたウィンドウにする。

オプション引数norecordが非nilの場合、この関数はもっとも最近に選択されたウィンドウのリストとバッファーリストを、どちらも変更しない。

Function: window-use-time &optional window

This functions returns the use time of window window. window must be a live window and defaults to the selected one.

The use time of a window is not really a time value, but an integer that does increase monotonically with each call of select-window with a nil norecord argument. The window with the lowest use time is usually called the least recently used window while the window with the highest use time is called the most recently used one (see section ウィンドウのサイクル順).

28.10 ウィンドウのサイクル順

他のウィンドウを選択するためにコマンドC-x o(other-window)を使う際には、特定の順番で生きたウィンドウを巡回します。与えられた任意のウィンドウ構成にたいして、この順序は決して変更されません。これは、ウィンドウのサイクル順序(cyclic ordering of windows)と呼ばれます。

The ordering is determined by a depth-first traversal of each frame’s window tree, retrieving the live windows which are the leaf nodes of the tree (see section ウィンドウとフレーム). If the minibuffer is active, the minibuffer window is included too. The ordering is cyclic, so the last window in the sequence is followed by the first one.

Function: next-window &optional window minibuf all-frames

この関数は、ウィンドウのサイクル順でwindowの次の生きたウィンドウをリターンする。windowは生きたウィンドウであること。省略またはnilの場合のデフォルトは選択されたウィンドウである。

The optional argument minibuf specifies whether minibuffer windows should be included in the cyclic ordering. Normally, when minibuf is nil, a minibuffer window is included only if it is currently active; this matches the behavior of C-x o. (Note that a minibuffer window is active as long as its minibuffer is in use; see ミニバッファー).

minibufがtの場合、サイクル順にはすべてのミニバッファーウィンドウが含まれる。minibufがtとnilのいずれとも異なる場合は、たとえアクティブであってもミニバッファーウィンドウは含まれない。

オプション引数all-framesは、考慮に入れるフレームを指定する:

nil を指定した場合は、windowのフレーム上にあるウィンドウを考慮することを意味する。。(minibuf引数で指定されたことにより)ミニバッファーウィンドウが考慮される場合は、ミニバッファーウィンドウを共有するフレームも考慮される。
t を指定した場合は、すべての既存フレーム上のウィンドウを考慮することを意味する。
visible を指定した場合は、すべての可視フレーム上のウィンドウを考慮することを意味する。
0 を指定した場合は、可視またはアイコン化されたすべてのフレーム上のウィンドウを考慮することを意味する。
フレームを指定した場合は、指定されたフレーム上のウィンドウを考慮することを意味する。
その他を指定した場合は、windowのあるフレーム上のウィンドウを考慮し、それ以外は考慮しないことを意味する。

複数のフレームが考慮される場合は、すべての生きたフレームのリストの順にしたがってそれらのフレームを順に追加することにより、サイクル順を取得する(すべてのフレームを探すを参照)。

Function: previous-window &optional window minibuf all-frames: この関数は、ウィンドウのサイクル順においてwindowの前に位置する、生きたウィンドウをリターンする。その他の引数は、next-windowの場合と同様に処理される。

Command: other-window count &optional all-frames

この関数は、ウィンドウのサイクル順において、選択されたウィンドウからcount番目に位置する、生きたウィンドウをリターンする。countが正の数ならcount個のウィンドウを前方にスキップし、負の数なら-count個のウィンドウを後方にスキップする。countが0の場合は、選択されたウィンドウを単に再選択する．インタラクティブに呼び出された場合、countはプレフィックス数引数である。

オプション引数all-framesは、next-windowにnilのminibuf引数を指定したときのnext-windowの場合と同じ意味をもつ。

この関数は、非nilのウィンドウパラメーターno-other-windowをもつウィンドウを選択しない。

Function: walk-windows fun &optional minibuf all-frames

この関数は、生きたウィンドウそれぞれにたいして、ウィンドウを引数に関数funを呼び出す。

これはウィンドウのサイクル順にしたがう。オプション引数minibufとall-framesは、含まれるウィンドウセットを指定する。これらは、next-windowの引数の場合と同じ意味をもつ。all-framesがフレームを指定する場合、最初に処理されるのはそのフレームの最初のウィンドウ(frame-first-windowがリターンするウィンドウ)であり、選択されたウィンドウである必要はない。

funがウィンドウの分割や削除によりウィンドウ構成を変更する場合でも、処理するウィンドウセットは初回のfun呼び出しに先立ち決定されるため、変更されない。

Function: one-window-p &optional no-mini all-frames

この関数は、選択されたウィンドウが唯一の生きたウィンドウの場合はt、それ以外はnilをリターンする。

ミニバッファーウィンドウがアクティブな場合、ミニバッファーウィンドウは通常は考慮される(そのため、この関数はnilをリターンする)。しかし、オプション引数no-miniが非nilの場合は、たとえアクティブであっても、ミニバッファーウィンドウは無視される。オプション引数all-framesは、next-windowの場合と同じ意味をもつ。

以下は、何らかの条件を満足するウィンドウを、それらを選択することなくリターンする関数です:

Function: get-lru-window &optional all-frames dedicated not-selected

This function returns a live window which is heuristically the least recently used. The optional argument all-frames has the same meaning as in next-window.

フル幅のウィンドウが存在する場合は、それらのウィンドウだけが考慮される。ミニバッファーが候補になることは、決してない。オプション引数dedicatedがnilの場合は、専用のバッファー(専用のウィンドウを参照)が候補になることは、決してない。唯一の候補が選択されたウィンドウである場合以外は、決して選択されたウィンドウをリターンしない。しかし、オプション引数not-selectedが非nilならば、そのような場合でもこの関数はnilをリターンする。

Function: get-mru-window &optional all-frames dedicated not-selected: This function is like get-lru-window, but it returns the most recently used window instead. The meaning of the arguments is the same as described for get-lru-window.

Function: get-largest-window &optional all-frames dedicated not-selected

この関数は、もっとも大きいエリア(高さ掛ける幅)をもつウィンドウをリターンする。オプション引数all-framesは検索するウィンドウを指定し、意味はnext-windowの場合と同様。

ミニバッファーウィンドウは決して候補とならない。オプション引数dedicatedがnilの場合、専用ウィンドウ(専用のウィンドウウィンドウを参照)は決して候補にならない。オプション引数not-selectedが非nilの場合、選択されたウィンドウは決して候補にならない。オプション引数not-selectedが非nil、かつ唯一の候補が選択されたウィンドウの場合、この関数はnilをリターンする。

同サイズの候補ウィンドウが2つある場合、この関数はウィンドウのサイクル順で、選択されたウィンドウから数えて最初にあるウィンドウを優先する。

Function: get-window-with-predicate predicate &optional minibuf all-frames default

この関数は、ウィンドウのサイクル順内の各ウィンドウにたいして、そのウィンドウを引数に、関数predicateを順に呼び出す。いずれかのウィンドウにたいしてpredicateが非nilをリターンした場合、この関数は処理を停止して、そのウィンドウをリターンする。そのようなうｌが見つからなければ、リターン値はdefault(これのデフォルトはnil)となる。

オプション引数 minibufとall-framesは検索するウィンドウを指定し、意味はnext-windowの場合と同様である。

28.11 バッファーとウィンドウ

このセクションでは、ウィンドウのコンテンツを調べたりセットするための、低レベルな関数を説明します。ウィンドウ内に特定のバッファーを表示するための高レベルな関数については、ウィンドウ内のバッファーへの切り替えを参照してください。

Function: window-buffer &optional window: この関数は、windowが表示しているバッファーをリターンする。windowが省略またはnilの場合のデフォルトは、選択されたウィンドウである。windowが内部ウィンドウの場合、この関数はnilをリターンする。

Function: set-window-buffer window buffer-or-name &optional keep-margins

この関数は、 windowにbuffer-or-nameウィンドウ表示させる。windowは生きたウィンドウであること。nilの場合のデフォルトは、選択されたウィンドウである。buffer-or-nameは、バッファー、あるいは既存のバッファー名であること。この関数は、選択されていたウィンドウを変更せず、カレントバッファーも直接は変更しない(カレントバッファーを参照)。リターン値はnilである。

windowが、あるバッファーにたいして特に専用で、かつbuffer-or-nameがそのバッファーを指定しない場合、この関数はエラーをシグナルする。専用のウィンドウを参照のこと。

By default, this function resets window’s position, display margins, fringe widths, and scroll bar settings, based on the local variables in the specified buffer. However, if the optional argument keep-margins is non-nil, it leaves window’s display margins, fringes and scroll bar settings alone.

アプリケーションを記述する際は、直接set-window-bufferを呼び出すのではなく、通常はウィンドウ内のバッファーへの切り替えで説明する高レベルの関数を使用するべきである。

これは、window-scroll-functionsの後にwindow-configuration-change-hookを実行する。ウィンドウのスクロールと変更のためのフックを参照のこと。

Variable: buffer-display-count: このバッファーローカル変数は、ウィンドウ内にバッファーが表示された回数を記録する。。これは、そのバッファーにたいしてset-window-bufferが呼び出されるたびに増分される

Variable: buffer-display-time: このバッファーローカル変数は、バッファーがウィンドウに最後に表示された時刻を記録する。バッファーが表示されたことがない場合は、nilをリターンする。これは、そのバッファーにたいしてset-window-bufferが呼び出されるたびに、current-timeがリターンする値により更新される(時刻を参照)。

Function: get-buffer-window &optional buffer-or-name all-frames

この関数は、ウィンドウのサイクル順内で、選択されたウィンドウを起点に、buffer-or-nameを表示する最初のウィンドウをリターンする.<(ウィンドウのサイクル順を参照)。そのようなウィンドウが存在しない場合、リターン値はnilとなる。

buffer-or-nameはバッファーか、バッファーの名前であること。省略またはnilの場合のデフォルトは、カレントバッファーである。オプション引数all-framesは、考慮するウィンドウを指定する。

tは、すべての既存フレーム上のウィンドウを考慮することを意味する。
visibleは、すべての可視フレーム上のウィンドウを考慮することを意味する。
0は、すべての可視またはアイコン化されたフレーム上のウィンドウを考慮することを意味する。
フレームを指定した場合は、そのフレーム上のウィンドウだけを考慮することを意味する。
その他の値は、選択されたフレーム上のウィンドウを考慮することを意味する。

これらの意味は、next-windowのall-frames引数の場合とは若干異なることに注意されたい(ウィンドウのサイクル順を参照)。この不一致の解消のために、EEmacsの将来のバージョンにおいて、この関数は変更されるかもしれない。

Function: get-buffer-window-list &optional buffer-or-name minibuf all-frames

This function returns a list of all windows currently displaying buffer-or-name. buffer-or-name should be a buffer or the name of an existing buffer. If omitted or nil, it defaults to the current buffer. If the currently selected window displays buffer-or-name, it will be the first in the list returned by this function.

引数minibufとall-framesは、関数next-windowの場合と同じ意味をもつ(ウィンドウのサイクル順を参照)。all-frames引数は、get-buffer-windowの場合と正確に同じようには振る舞わないことに注意すること。

Command: replace-buffer-in-windows &optional buffer-or-name

このコマンドは、buffer-or-nameを表示しているすべてのウィンドウで、それを他の何らかのバッファーに置き換える。buffer-or-nameはバッファー、または既存のバッファーの名前であること。省略またはnilの場合のデフォルトは、カレントバッファーである。

各ウィンドウで置き換えられるバッファーは、switch-to-prev-bufferを通じて選択される(ウィンドウのヒストリーを参照)。buffer-or-nameを表示している専用ウィンドウはすべて、可能なら削除される(専用のウィンドウを参照)。そのようなウィンドウがそのフレームで唯一のウィンドウで、かつ同一端末上に他のフレームが存在する場合は、そのフレームも同様に削除される。その端末上の唯一のフレームの唯一のウィンドウの場合は、いずれにせよそのバッファーは置き換えられる。

28.12 ウィンドウ内のバッファーへの切り替え

このセクションでは、あるウィンドウ内で特定のバッファーにスイッチするための、高レベルな関数について説明します。“バッファーをスイッチする”とは一般的に、(1)そのバッファーをあるウィンドウに表示して、(2)そのウィンドウを選択されたウィンドウとし(かつそのフレームを選択されたフレームとし、(3)そのバッファーウィンドウカレントバッファーにすることを意味します。

Lispプログラムがアクセスや変更できるように、バッファーを一時的にカレントにするのにこれらの関数を使用しないでください。これらはウィンドウヒストリー(ウィンドウのヒストリーを参照)の変更のような副作用をもつので、そのような方法での使用はユーザーを驚かせることになるでしょう。バッファーをLispで変更するためにカレントにしたい場合はwith-current-buffer、save-current-buffer、set-bufferを使用します。カレントバッファーを参照してください。

Command: switch-to-buffer buffer-or-name &optional norecord force-same-window

このコマンドは、選択されたウィンドウ内でbuffer-or-nameを表示して、それをカレントバッファーにしようと試みる。これはよくインタラクティブ(C-x bのバインディングで)に使用され、同様にLispプログラムでも使用される。リターン値はスイッチしたバッファーである。

buffer-or-nameがnilの場合のデフォルトは、other-bufferによりリターンされるバッファーになる(バッファーリストを参照)。buffer-or-nameが既存のバッファーの名前でない文字列の場合、この関数はその名前で新たにバッファーを作成する。新たなバッファーのメジャーモードは、変数major-modeにより決定される(メジャーモードを参照)。

通常は、指定されたバッファーはバッファーリスト — グローバルバッファーリストと選択されたフレームのバッファーリストの両方の先頭に置かれる(バッファーリストを参照)。しかし、オプション引数norecordが非nilなら、これは行われない。

Sometimes, the selected window may not be suitable for displaying the buffer. This happens if the selected window is a minibuffer window, or if the selected window is strongly dedicated to its buffer (see section 専用のウィンドウ). In such cases, the command normally tries to display the buffer in some other window, by invoking pop-to-buffer (see below).

If the optional argument force-same-window is non-nil and the selected window is not suitable for displaying the buffer, this function always signals an error when called non-interactively. In interactive use, if the selected window is a minibuffer window, this function will try to use some other window instead. If the selected window is strongly dedicated to its buffer, the option switch-to-buffer-in-dedicated-window described next can be used to proceed.

User Option: switch-to-buffer-in-dedicated-window

This option, if non-nil, allows switch-to-buffer to proceed when called interactively and the selected window is strongly dedicated to its buffer.

The following values are respected:

nil: Disallows switching and signals an error as in non-interactive use.
prompt: Prompts the user whether to allow switching.
pop: Invokes pop-to-buffer to proceed.
t: Marks the selected window as non-dedicated and proceeds.

This option does not affect non-interactive calls of switch-to-buffer.

By default, switch-to-buffer tries to preserve window-point. This behavior can be tuned using the following option.

User Option: switch-to-buffer-preserve-window-point

この変数がnilの場合、switch-to-bufferはbuffer-or-nameにより指定されたバッファーを、そのバッファーのpoint位置で表示する。この変数がalready-displayedなら、そのバッファーが任意の可視またはアイコン化されたフレーム上の他のウィンドウで表示されている場合は、選択されたウィンドウ内の以前の位置でのバッファーの表示を試みる。この変数がtなら、switch-to-bufferは選択されたウィンドウ内の以前の位置でそのバッファーを表示しようと試みる。

この変数は、バッファーがすでに選択されたウィンドウに表示されているか、これまで表示されたことがない、またはバッファーを表示するためにswitch-to-bufferがpop-to-bufferを呼び出した場合は無視される。

以下の2つのコマンドは、説明している機能以外はswitch-to-bufferと類似しています。

Command: switch-to-buffer-other-window buffer-or-name &optional norecord

この関数は、buffer-or-nameで指定されたバッファーを、選択されたウィンドウ以外の、別のウィンドウに表示する。これは関数pop-to-buffer(以下参照)を内部で使用する。

選択されたウィンドウが指定されたバッファーをすでに表示している場合は表示を続けるが、見つかった他のウィンドウも同様にそのバッファーを表示する。

引数buffer-or-nameとnorecordは、switch-to-bufferの場合と同じ意味をもつ。

Command: switch-to-buffer-other-frame buffer-or-name &optional norecord

この関数は、buffer-or-nameで指定されたバッファーを、新たなフレームに表示する。これは関数pop-to-buffer(以下参照)を内部で使用する。

指定されたバッファーがすでにカレント端末上の任意のフレームの他のウィンドウに表示されている場合、これはフレームを新たに作成せずにそのウィンドウに切り替える。しかし、これを行うために選択されたウィンドウを使用することは決してない。

引数buffer-or-nameとnorecordは、switch-to-bufferの場合と同じ意味をもつ。

上述したコマンドは、任意のウィンドウにバッファーを柔軟に表示して、編集用にそのウィンドウを選択する関数pop-to-bufferを使用しています。次に、pop-to-bufferはバッファーの表示にdisplay-bufferを使用します。したがって、display-bufferに影響する変数も、同様に影響します。display-bufferのドキュメントについては、表示するウィンドウの選択を参照してください。

Command: pop-to-buffer buffer-or-name &optional action norecord

This function makes buffer-or-name the current buffer and displays it in some window, preferably not the window currently selected. It then selects the displaying window. If that window is on a different graphical frame, that frame is given input focus if possible (see section 入力のフォーカス).

If buffer-or-name is nil, it defaults to the buffer returned by other-buffer (see section バッファーリスト). If buffer-or-name is a string that is not the name of any existing buffer, this function creates a new buffer with that name; the new buffer’s major mode is determined by the variable major-mode (see section メジャーモード). In any case, that buffer is made current and returned, even when no suitable window was found to display it.

actionが非nilの場合、それはdisplay-bufferに渡すディスプレイアクション(display action)であること(表示するウィンドウの選択を参照)。非nil、非リスト値の場合は、たとえそのバッファーがすでに選択されたウィンドウに表示されていたとしても、選択されたウィンドウではなく、ウィンドウをポップ(pop)することを意味する。

switch-to-bufferと同様、norecordがnilなら、この関数はバッファーリストを更新する。

28.13 表示するウィンドウの選択

コマンドdisplay-bufferは、表示のために柔軟にウィンドウを選択して、そのウィンドウ内に指定されたバッファーを表示します。これは、キーバインディングC-x 4 C-oを通じて、インタラクティブに呼び出すことができます。また、switch-to-bufferやpop-to-bufferを含む、多くの関数およびコマンドにより、サブルーチンとしても使用されます(ウィンドウ内のバッファーへの切り替えを参照)。

This command performs several complex steps to find a window to display in. These steps are described by means of display actions, which have the form (function . alist). Here, function is either a function or a list of functions, which we refer to as action functions; alist is an association list, which we refer to as an action alist.

アクション関数は、表示するバッファーと、アクションalistという、2つの引数を受け取ります。これは、自身の条件にしたがってウィンドウウィンドウ選択、または作成して、バッファーをウィンドウ内に表示します。成功した場合はそのウィンドウ、それ以外はnilをリターンします。事前定義されたアクション関数については、display-bufferにたいするアクション関数を参照してください。

display-bufferは、複数ソースからのディスプレイアクションを組み合わせて、アクション関数のいずれか1つがバッファーの表示を管理して非nil値をリターンするまで、アクション関数を順に呼び出します。

Command: display-buffer buffer-or-name &optional action frame

このコマンドは、ウィンドウウィンドウ選択したり、そのバッファーをカレントにすることなく、buffer-or-nameをウィンドウに表示させる。引数buffer-or-nameはバッファー、または既存のバッファーの名前でなければならない。リターン値は、そのバッファーを表示するために選ばれたウィンドウである。

オプション引数actionが非nilの場合、それは通常はディスプレイアクション(上述)であること。display-bufferは、以下のソース(記載順)からディスプレイアクションを集約して、アクション関数リストとアクションalistを構築する:

変数display-buffer-overriding-action。
ユーザーオプションdisplay-buffer-alist。
action引数。
ユーザーオプションdisplay-buffer-base-action。
定数display-buffer-fallback-action。

各アクション関数は、いずれかが非nilをリターンするまで、第1引数にバッファー、第2引数に組み合わせられたアクションalistで、順番に呼び出される。呼び出し側は、ウィンドウ内にバッファーを表示しない場合を処理する用意があることを示すために、アクションalistの要素として(allow-no-window . t)を渡すことができる。

引数actionには非nilの非list値も指定できる。これは、たとえ選択されたウィンドウがすでにそのバッファーを表示していても、選択されたウィンドウではない別のウィンドウにバッファーが表示されるべきだという、特別な意味をもつ。プレフィックス引数とともにインタラクティブに呼び出された場合、actionはtである。

オプション引数frameが非nilの場合は、そのバッファーがすでに表示されているか判断する際、どのフレームをチェックするかを指定する。これはactionのアクションalistに、要素(reusable-frames . frame)を追加するのと等価である。display-bufferにたいするアクション関数を参照のこと。

Variable: display-buffer-overriding-action: この変数の値は、display-bufferにより最高の優先順で扱われるディスプレイアクションであること。デフォルト値は空(つまり(nil . nil))である。

User Option: display-buffer-alist: このオプションの値は、ディスプレイアクションにコンディション(condition: 状態)をマップするalistである。コンディションはそれぞれ、バッファー名にマッチする正規表現か、2つの引数をとる関数で、引数はバッファー名とdisplay-bufferに渡すaction引数である。display-bufferに渡されたバッファー名がこのalist内の正規表現にマッチするか、コンディションで指定された関数が非nilをリターンした場合、display-bufferはバッファーを表示すために、対応するディスプレイアクションを使用する。

User Option: display-buffer-base-action: The value of this option should be a display action. This option can be used to define a standard display action for calls to display-buffer.

Constant: display-buffer-fallback-action: このディスプレイアクションは、display-bufferにたいして、他のディスプレイアクションが与えられなかった場合の代替え処理を指定する。

28.14 `display-buffer`にたいするアクション関数

以下の基本的なアクション関数がEmacs内で定義されています。これらの関数はそれぞれ表示するバッファーbufferと、アクションalistという、2つの引数をとります。それぞれのアクション関数は、成功した場合はウィンドウ、失敗したらnilをリターンします。

Function: display-buffer-same-window buffer alist: この関数は、選択されたウィンドウ内に、bufferの表示を試みる。選択されたウィンドウがミニバッファーウィンドウや、他のバッファー専用(専用のウィンドウを参照)の場合は失敗する。alistに非nilのinhibit-same-windowエントリーがある場合も失敗する。

Function: display-buffer-reuse-window buffer alist

This function tries to display buffer by finding a window that is already displaying it.

alistに非nilのinhibit-same-windowエントリーがある場合、選択されたウィンドウは再利用に適さない。alistにreusable-framesエントリーが含まれる場合、その値により再利用可能なウィンドウをどのフレームで検索するか決定される:

nilは、選択されたフレーム(実際には最後の非ミニバッファーフレーム)上のウィンドウを考慮することを意味する。
tは、すべてのフレーム上のウィンドウを考慮することを意味する。
visibleは、すべての可視フレーム上のウィンドウを考慮することを意味する。
0は、すべての可視またはアイコン化されたフレーム上のウィンドウを考慮することを意味する。
フレームを指定した場合は、そのフレーム上のウィンドウだけを考慮することを意味する。

これらは、next-windowにたいするall-frames引数の場合とは若干異なることに注意(ウィンドウのサイクル順を参照)。

alistにreusable-framesエントリーが含まれない場合、通常この関数は選択されたフレームだけを検索する。しかし、変数pop-up-framesが非nilなら、カレント端末上のすべてのフレームを検索する。バッファー表示の追加オプションを参照。

この関数が他のフレーム上のウィンドウを選択した場合は、そのフレームを可視にするとともに、alistがinhibit-switch-frameエントリー(バッファー表示の追加オプションを参照)を含んでいなければ、必要ならそのフレームを最前面に移動(raise)する。

Function: display-buffer-reuse-mode-window buffer alist

This function tries to display buffer by finding a window that is displaying a buffer in a given mode.

If alist contains a mode entry, its value is a major mode (a symbol) or a list of major modes. If alist contains no mode entry, the current major mode of buffer is used. A window is a candidate if it displays a buffer that derives from one of the given modes.

The behavior is also controlled by entries for inhibit-same-window, reusable-frames and inhibit-switch-frame as is done in the function display-buffer-reuse-window.

Function: display-buffer-pop-up-frame buffer alist: この関数は、新たにフレームを作成して、そのフレームのウィンドウ内にバッファーを表示する。これは実際には、pop-up-frame-function(バッファー表示の追加オプションを参照)内で指定された関数を呼び出すことにより、フレーム作成を行う。alistがpop-up-frame-parametersエントリーを含む場合は、その連想値(associated value)が新たに作成されたフレームのパラメーターに追加される。

Function: display-buffer-in-child-frame buffer alist

This function tries to display buffer in a child frame (see section Child Frames) of the selected frame, either reusing an existing child frame or by making a new one. If alist has a non-nil child-frame-parameters entry, the corresponding value is an alist of frame parameters to give the new frame. A parent-frame parameter specifying the selected frame is provided by default. If the child frame should be or become the child of another frame, a corresponding entry must be added to alist.

The appearance of child frames is largely dependent on the parameters provided via alist. It is advisable to use at least ratios to specify the size (see section サイズのパラメーター) and the position (see section 位置のパラメーター) of the child frame and to add the keep-ratio in order to make sure that the child frame remains visible. For other parameters that should be considered see Child Frames.

Function: display-buffer-use-some-frame buffer alist

This function tries to display buffer by trying to find a frame that meets a predicate (by default any frame other than the current frame).

If alist has a non-nil frame-predicate entry, its value is a function taking one argument (a frame), returning non-nil if the frame is a candidate; this function replaces the default predicate.

If alist has a non-nil inhibit-same-window entry, the selected window is used; thus if the selected frame has a single window, it is not used.

Function: display-buffer-pop-up-window buffer alist

この関数は、最大もしくはもっとも長い間参照されていない(LRU: least recently-used)ウィンドウを分割することにより、bufferの表示を試みる。これは実際には、split-window-preferred-function(バッファー表示の追加オプションを参照)内で指定された関数を呼び出すことにより分割を行う。

新たなウィンドウのサイズは、alistにエントリーwindow-heightとwindow-widthを与えることにより調整できる。ウィンドウの高さを調整するには、CARがwindow-heightでCDRが以下のいずれかであるようなエントリーを使用する:

nilは、新たなウィンドウの高さを変更しないことを意味する。
数字は、新たなウィンドウの高さを指定する。整数は、ウィンドウの行数を指定する。浮動小数点数は、そのフレームのルートウィンドウにたいするウィンドウの高さの割合を与える。
CDRが関数を指定する場合、その関数は新たなウィンドウを引数として呼び出される関数である。この関数は、そのウィンドウの高さを調整することを期待されており、リターン値は無視される。これに適した関数はshrink-window-if-larger-than-bufferおよびfit-window-to-bufferである。ウィンドウのリサイズを参照のこと。

ウィンドウの幅を調整するには、CARがwindow-widthでCDRが以下のいずれかであるようなエントリーを使用する:

nilは、新たなウィンドウの幅を変更しないことを意味する。
数字は、新たなウィンドウの幅を指定する。整数は、ウィンドウの列数を指定する。浮動小数点数は、そのフレームのルートウィンドウにたいするウィンドウの幅の割合を与える。
CDRが関数を指定する場合、その関数は新たなウィンドウを引数として呼び出される関数である。この関数は、そのウィンドウの幅を調整することを期待されており、リターン値は無視される。

If alist contains a preserve-size entry, Emacs will try to preserve the size of the new window during future resize operations (see section Preserving Window Sizes). The CDR of that entry must be a cons cell whose CAR, if non-nil, means to preserve the width of the window and whose CDR, if non-nil, means to preserve the height of the window.

この関数は、何らかの理由により分割を行えるウィンドウが存在しない場合は、失敗する可能性がある(選択されたフレームがフレームパラメーターunsplittableをもつ場合等。バッファーのパラメーターを参照のこと)。

Function: display-buffer-below-selected buffer alist

This function tries to display buffer in a window below the selected window. If there is a window below the selected one and that window already displays buffer, it reuses that window.

If there is no such window, this function tries to create a new window by splitting the selected one and display buffer there. It will also adjust that window’s size provided alist contains a suitable window-height or window-width entry, see above.

If splitting the selected window fails and there is a non-dedicated window below the selected one showing some other buffer, it uses that window for showing buffer.

Function: display-buffer-in-previous-window buffer alist

この関数は、以前にbufferを表示していたウィンドウ内に、そのバッファーの表示を試みる。alistに非nilのinhibit-same-windowエントリーがある場合、選択されたウィンドウは再利用に適さない。alistにreusable-framesエントリーが含まれる場合、その値はdisplay-buffer-reuse-windowと同様、適正なウィンドウをどのフレームから検索するかを決定する。

alistにprevious-windowエントリーがある場合は、そのエントリーにより指定されたウィンドウは、たとえそのウィンドウが以前にbufferを表示したことが一度もなくても、上記メソッドが見つけた他のすべてのウィンドウをオーバーライドするだろう。

Function: display-buffer-at-bottom buffer alist

この関数は、選択されたフレームの最下にあるウィンドウ内にbufferの表示を試みる。

これは、フレーム最下のウィンドウまたはフレームのルートウィンドウを分割するか、選択されたフレーム最下の既存ウィンドウを再利用する。

Function: display-buffer-use-some-window buffer alist: この関数は、既存のウィンドウを選択して、そのウィンドウ内にbufferを表示することにより、バッファーの表示を試みる。すべてのウィンドウが他のバッファー専用の場合、この関数は失敗する可能性がある(専用のウィンドウを参照)。

Function: display-buffer-no-window buffer alist: If alist has a non-nil allow-no-window entry, then this function does not display buffer. This allows you to override the default action and avoid displaying the buffer. It is assumed that when the caller specifies a non-nil allow-no-window value it can handle a nil value returned from display-buffer in this case.

If the alist argument of any of these functions contains a window-parameters entry, display-buffer assigns the elements of the associated value as window parameters of the chosen window.

アクション関数を説明するために、以下の例を考えてみましょう。

(display-buffer
 (get-buffer-create "*foo*")
 '((display-buffer-reuse-window
    display-buffer-pop-up-window
    display-buffer-pop-up-frame)
   (reusable-frames . 0)
   (window-height . 10) (window-width . 40)))

上記のフォームを評価することにより、以下のようにdisplay-bufferが実行されます: (1)*foo*と呼ばれるバッファーが、すでに可視またはアイコン化されたフレームに表示されている場合は、そのウィンドウを再利用する。 (2)それ以外の場合は、新たなウィンドウをポップアップするか、それが不可能なら新たなフレームでバッファーを表示する。(3) すべてのステップが失敗した場合は、それが何であれdisplay-buffer-base-actionおよびdisplay-buffer-fallback-actionが指示するものを使用して処理を行う。

Furthermore, display-buffer will try to adjust a reused window (provided *foo* was put by display-buffer there before) or a popped-up window as follows: If the window is part of a vertical combination, it will set its height to ten lines. Note that if, instead of the number 10, we specified the function fit-window-to-buffer, display-buffer would come up with a one-line window to fit the empty buffer. If the window is part of a horizontal combination, it sets its width to 40 columns. Whether a new window is vertically or horizontally combined depends on the shape of the window split and the values of split-window-preferred-function, split-height-threshold and split-width-threshold (see section バッファー表示の追加オプション).

Now suppose we combine this call with a preexisting setup for display-buffer-alist as follows.

(let ((display-buffer-alist
       (cons
        '("\\*foo\\*"
          (display-buffer-reuse-window display-buffer-below-selected)
          (reusable-frames)
          (window-height . 5))
        display-buffer-alist)))
  (display-buffer
   (get-buffer-create "*foo*")
   '((display-buffer-reuse-window
      display-buffer-pop-up-window
      display-buffer-pop-up-frame)
     (reusable-frames . 0)
     (window-height . 10) (window-width . 40))))

このフォームは、まず選択されたフレーム上で*foo*を表示しているウィンドウを再利用するよう、display-bufferに試みさせます。そのようなウィンドウが存在しなければ、選択されたウィンドウの分割を試み、またはそれが不可能なら選択されたウィンドウの下のウィンドウを使用します。

If there’s no window below the selected one, or the window below the selected one is dedicated to its buffer, display-buffer will proceed as described in the previous example. Note, however, that when it tries to adjust the height of any reused or popped-up window, it will in any case try to set its number of lines to 5 since that value overrides the corresponding specification in the action argument of display-buffer.

28.15 バッファー表示の追加オプション

display-bufferの標準のディスプレイアクション(see section 表示するウィンドウの選択)は、さまざまなユーザーオプションにより変更が可能です。

User Option: pop-up-windows

この変数の値が非nilの場合、display-bufferは表示のために既存のバッファーを分割して新たなウィンドウの作成を許される。

この変数は、主に後方互換のために提供される。値がnilのときは、アクション関数display-buffer-pop-up-window(display-bufferにたいするアクション関数を参照)を呼び出すだけのdisplay-buffer-fallback-action内の特別なメカニズムを経由して、display-bufferにしたがう。この変数は、display-buffer-alist等により直接指定できる、display-buffer-pop-up-window自体からは参照されない。

User Option: split-window-preferred-function

この変数は、バッファーを表示する新たなウィンドウを作成するための、ウィンドウを分割する関数を指定する。これは、実際にウィンドウを分割するために、アクション関数display-buffer-pop-up-windowにより使用される(display-bufferにたいするアクション関数を参照)。

デフォルト値はsplit-window-sensiblyで、これは以下で記述する。値は、ウィンドウを引数とする関数でなければならず、(要求されたバッファーを表示するために使用されるであろう)新たなウィンドウ、またはnil(分割の失敗を意味する)をリターンしなければならない。

Function: split-window-sensibly &optional window

This function tries to split window, and return the newly created window. If window cannot be split, it returns nil. If window is omitted or nil, it defaults to the selected window.

この関数は、ウィンドウが分割できるかどうか判断する際の、通常のルールにしたがう(ウィンドウの分割を参照)。最初にまず、split-height-threshold(以下参照)、およびその他が課す制約の元、新たなウィンドウが下になるように分割を試みる。これが失敗したら、split-width-threshold(以下参照)が課す制約の元、新たなウィンドウが右になるように分割を試みる。これが失敗して、かつそのウィンドウがそのフレームの唯一のウィンドウの場合、この関数はsplit-height-thresholdを無視して、新たなウィンドウが下になるよう、再度分割を試みる。これも同様に失敗したら、この関数は諦めてnilをリターンする。

User Option: split-height-threshold: これはsplit-window-sensiblyにより使用される変数であり、ウィンドウを分割して新たなウィンドウを下に配置するかどうかを指定する。整数の場合は、元のウィンドウが最低でもその行数なければ分割しないことを意味する。nilの場合は、この方法では分割しないことを意味する。

User Option: split-width-threshold: これはsplit-window-sensiblyにより使用される変数であり、ウィンドウを分割して新たなウィンドウを右に配置するかどうかを指定する。整数の場合は、元のウィンドウが最低でもその列数なければ分割しないことを意味する。nilの場合は、この方法では分割しないことを意味する。

User Option: even-window-sizes

This variable, if non-nil, causes display-buffer to even window sizes whenever it reuses an existing window and that window is adjacent to the selected one.

If its value is width-only, sizes are evened only if the reused window is on the left or right of the selected one and the selected window is wider than the reused one. If its value is height-only sizes are evened only if the reused window is above or beneath the selected window and the selected window is higher than the reused one. Any other non-nil value means to even sizes in any of these cases provided the selected window is larger than the reused one in the sense of their combination.

User Option: pop-up-frames

この変数の値が非nilの場合、新たにフレームを作成することによりdisplay-bufferがバッファーを表示できることを意味する。デフォルトはnil。

非nil値は、display-bufferがすでにbuffer-or-nameを表示しているウィンドウを探す際に、選択されたフレームだけでなく、可視およびアイコン化されたフレームを検索できることも意味する。

この変数は主に、後方互換のために提供されている。値が非nilのときは、アクション関数display-buffer-pop-up-frame(display-bufferにたいするアクション関数を参照)を呼び出すだけのdisplay-buffer-fallback-action内の特別なメカニズムを経由して、display-bufferにしたがう。この変数は、display-buffer-alist等により直接指定できる、display-buffer-pop-up-window自体からは参照されない(これはウィンドウの分割前に行われる)。この変数は、display-buffer-alist等により直接指定できる、display-buffer-pop-up-frame自体からは参照されない。

User Option: pop-up-frame-function

この変数は、バッファーを表示する新たなウィンドウを作成するための、フレームを作成する関数を指定する。これは、アクション関数display-buffer-pop-up-frameにより使用される(display-bufferにたいするアクション関数を参照)。

値は、フレームまたはフレームを作成できなかった場合はnilをリターンする、引数をとらない関数であること。デフォルト値は、pop-up-frame-alist(以下参照)により指定されるパラメーターを使用してフレームを作成する関数である。

User Option: pop-up-frame-alist: この変数は、フレームを新たに作成するためのpop-up-frame-functionのデフォルト関数により使用される、フレームパラメーター(フレームのパラメーターを参照)のalistを保持する。デフォルトはnil。

User Option: same-window-buffer-names: 選択されたウィンドウ内に表示されるべきバッファー名のリスト。このリスト内にバッファーの名前がある場合、display-bufferは選択されたウィンドウ内にそのバッファーを表示することにより、そのバッファーを処理する。

User Option: same-window-regexps: 選択されたウィンドウ内に表示されるバッファーを指定する、正規表現のリスト。バッファー名がこのリスト内の正規表現のいずれかにマッチする場合、display-bufferは選択されたウィンドウ内にそのバッファーを表示することにより、そのバッファーを処理する。

Function: same-window-p buffer-name: この関数は、buffer-nameという名前のバッファーをdisplay-bufferで表示する場合、それが選択されたウィンドウ内に表示されるバッファーならtをリターンする。

28.16 ウィンドウのヒストリー

Each window remembers in a list the buffers it has previously displayed, and the order in which these buffers were removed from it. This history is used, for example, by replace-buffer-in-windows (see section バッファーとウィンドウ), and when quitting windows (see section ウィンドウのquit). The list is automatically maintained by Emacs, but you can use the following functions to explicitly inspect or alter it:

Function: window-prev-buffers &optional window

この関数は、windowの前のコンテンツを指定するリストをリターンする。オプション引数windowには生きたウィンドウを指定すべきであり、デフォルトは選択されたウィンドウである。

リスト要素はそれぞれ、(buffer window-start window-pos)という形式をもつ。ここでbufferは、そのウィンドウで前に表示されていたウィンドウ、window-startはそのバッファーが最後に表示されていたときのウィンドウのスタート位置(ウィンドウの開始位置と終了位置を参照)、window-posはwindow内にそのバッファーが最後に表示されていたときのポイント位置(ウィンドウとポイントを参照)である。

このリストは順序付きで、より前の要素がより最近に表示されたバッファーに対応しており、通常は最初の要素がそのウィンドウからもっとも最近削除されたバッファーに対応する。

Function: set-window-prev-buffers window prev-buffers: この関数は、windowの前のバッファーを、prev-buffersの値にセットする。引数windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。引数prev-buffersは、window-prev-buffersによりリターンされるリストと同じ形式であること。

これらに加えて、それぞれのバッファーは次バッファー(next buffers)のリストを保守します。これはswitch-to-prev-buffer(以下参照)により再表示されたバッファーのリストです。このリストは主に、切り替えるバッファーを選択するために、switch-to-prev-bufferとswitch-to-next-bufferにより使用されます。

Function: window-next-buffers &optional window: この関数は、switch-to-prev-bufferを通じてwindow内に最近表示されたバッファーのリストをリターンする。window引数は、生きたウィンドウかnil(選択されたウィンドウの意)でなければならない。

Function: set-window-next-buffers window next-buffers: この関数は、windowの次バッファーリストを、next-buffersにセットする。window引数は、生きたウィンドウかnil(選択されたウィンドウの意)であること。引数next-buffersは、バッファーのリストであること。

以下のコマンドは、bury-bufferやunbury-bufferのように、グローバルバッファーリストを巡回するために使用できます。ただし、これらはグローバルバッファーリストではなく、指定されたウィンドウのヒストリーリストのしたがって巡回します。それに加えて、これらはウィンドウ固有なウィンドウのスタート位置とポイント位置をリストアし、すでに他のウィンドウに表示されているバッファーをも表示できます。特にswitch-to-prev-bufferコマンドは、ウィンドウにたいする置き換えバッファーを探すためにreplace-buffer-in-windows、bury-buffer、quit-windowにより使用されます。

Command: switch-to-prev-buffer &optional window bury-or-kill

このコマンドは、window内に前のバッファーを表示する。引数windowは生きたウィンドウ、またはnil(選択されたウィンドウの意)であること。オプション引数bury-or-killが非nil、それはwindow内にカレントで表示されているバッファーは今まさにバリーもしくはkillされるバッファーであり、したがって将来におけるこのコマンドの呼び出しで、このバッファーに切り替えるべきではないことを意味する。

前のバッファーは通常、window内にカレントで表示されているバッファーの前に表示されていたバッファーである。しかし、バリーまたはkillされたバッファー、または直近のswitch-to-prev-buffer呼び出しですでに表示されたバッファーは、前のバッファーとして適格とはならない。

このコマンドを繰り返して呼び出すことにより、window内で前に表示されたすべてのバッファーが表示されてしまった場合、将来の呼び出しにおいては、windowが表示されているフレームのバッファーリスト(バッファーリストを参照)から、そのフレームの他のウィンドウで表示済みのバッファーをスキップするようにして、バッファーを表示するだろう。

Command: switch-to-next-buffer &optional window

このコマンドは、window内の次バッファーに切り替える。つまり、window内での最後のswitch-to-prev-bufferコマンドの効果をアンドゥする。引数windowは生きたウィンドウであること。デフォルトは選択されたウィンドウである。

アンドゥ可能なswitch-to-prev-bufferの直近の呼び出しが存在しない場合、この関数はwindowが表示されているフレームのバッファーリスト(バッファーリストを参照)からバッファーの表示を試みる。

デフォルトでは、switch-to-prev-bufferとswitch-to-next-bufferは、同一フレーム上の他のウィンドウで表示済みのバッファーに切り替えることができます。以下のオプションは、この挙動をオーバーライドするために使用できます。

User Option: switch-to-visible-buffer: この変数が非nilの場合、switch-to-prev-bufferおよびswitch-to-next-bufferは、そのバッファーが当該ウィンドウで過去に表示されていれば、同一フレーム上ですでに可視のバッファーに切り替えることができる。nilの場合、switch-to-prev-bufferおよびswitch-to-next-bufferは、同一フレーム上ですでに可視なバッファーへの切り替えを常に避けるよう試みる。デフォルトはt。

28.17 専用のウィンドウ

バッファーを表示する関数は、特定のウィンドウが、そのウィンドウのバッファーにたいして専用(dedicated)であるとマークすることにより、使用しないよう告げることができます。display-buffer(表示するウィンドウの選択を参照)は、他のバッファーの表示に、専用バッファーを決して使用しません。 and get-largest-window(see section ウィンドウのサイクル順)は、dedicated引数が非nilのときは、専用ウィンドウを候補とみなしません。専用ウィンドウにたいする配慮に関して、set-window-buffer(バッファーとウィンドウを参照)の挙動は若干異なります。以下を参照してください。

ウィンドウからバッファー、およびフレームからウィンドウを削除することを意図した関数は、処理するウィンドウが専用ウィンドウのときは特別な挙動を示す可能性があります。ここでは3つの基本ケース、すなわち(1)そのウィンドウがフレーム上で唯一のウィンドウの場合、(2)ウィンドウはフレーム上で唯一のウィンドウだが同一端末上に別のフレームがある場合、(3)そのウィンドウが同一端末上で唯一のフレームの唯一のウィンドウの場合、を明確に区別することにします。

特に、delete-windows-on(ウィンドウの削除を参照)は関連するフレームを削除する際にケース(2)を、フレーム上で唯一のウィンドウに他のバッファーを表示する際にケース(3)を処理します。バッファーがkillされる際に呼び出される関数replace-buffer-in-windows(see section バッファーとウィンドウ)は、ケース(1)ではウィンドウを削除して、それ以外ではdelete-windows-onのように振る舞います。

bury-buffer(バッファーリストを参照)が選択されたウィンドウを操作する際は、選択されたフレームを処理するために、frame-auto-hide-function(ウィンドウのquitを参照)を呼び出すことにより、ケース(2)を取り扱います。他の2つのケースは、replace-buffer-in-windowsと同様に処理されます。

Function: window-dedicated-p &optional window: この関数は、windowがそのバッファーにたいして専用なら非nil、それ以外はnilをリターンする。より正確には、最後のset-window-dedicated-p呼び出しで割り当てられた値、またはset-window-dedicated-pがwindowを引数として呼び出されたことがない場合はnilがリターン値となる。windowのデフォルトは、選択されたウィンドウである。

Function: set-window-dedicated-p window flag

この関数は、flagが非nilならwindowがそのバッファーに専用とマークし、それ以外は非専用とマークする。

特別なケースとして、flagがtの場合、windowはそのバッファーにたいして特に専用(strongly dedicated)となる。set-window-bufferは、処理対象のウィンドウが特に専用のウィンドウで、かつ表示を要求されたバッファーが表示済みでない場合は、エラーをシグナルする。その他の関数は、tを他の非nil値と区別して扱わない。

28.18 ウィンドウのquit

バッファーを表示するために使用しているウィンドウを削除したいときは、フレームからそのウィンドウを削除するために、delete-windowやdelete-windows-onを呼び出すことができます(ウィンドウの削除を参照)。その、が別フレームで表示されているときは、かわりにdelete-frameを呼び出したいと思うかもしれません(フレームの削除を参照)。一方で、そのバッファーを表示するためにウィンドウが再利用されている場合は、関数switch-to-prev-bufferを呼び出して、前に表示されていたバッファーを表示したいと思うかもしれません(ウィンドウのヒストリーを参照)。最終的には、そのウィンドウのバッファーをバリー(バッファーリストを参照)、またはkill(バッファーのkillを参照)したいと思うかもしれません。

以下のコマンドは、ウィンドウがバッファーを表示する方法を最初に入手する情報を使用して、上述した説明の自動化を試みます。

Command: quit-window &optional kill window: このコマンドは、windowをquitして、そのバッファーをバリーする。引数windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。プレフィックス引数killが非nilなら、バッファーをバリーするかわりにkillする。これは、ウィンドウとそのバッファーを処理するために、次に説明する関数quit-restore-windowを呼び出す。

Function: quit-restore-window &optional window bury-or-kill

This function handles window and its buffer after quitting. The optional argument window must be a live window and defaults to the selected one. The function’s behavior is determined by the four elements of the quit-restore window parameter (see section ウィンドウのパラメーター), which is set to nil afterwards.

The window is deleted entirely if: 1) the first element of the quit-restore parameter is one of ’window or ’frame, 2) the window has no history of previously-displayed buffers, and 3) the displayed buffer matches the one in the fourth element of the quit-restore parameter. If window is the only window on its frame and there are other frames on the frame’s terminal, the value of the optional argument bury-or-kill determines how to proceed with the window. If bury-or-kill equals kill, the frame is deleted unconditionally. Otherwise, the fate of the frame is determined by calling frame-auto-hide-function (see below) with that frame as sole argument.

If the third element of the quit-restore parameter is a list of buffer, window start (see section ウィンドウの開始位置と終了位置), and point (see section ウィンドウとポイント), and that buffer is still live, the buffer will be displayed, and start and point set accordingly. If, in addition, window’s buffer was temporarily resized, this function will also try to restore the original height of window.

Otherwise, if window was previously used for displaying other buffers (see section ウィンドウのヒストリー), the most recent buffer in that history will be displayed.

オプション引数bury-or-killは、windowを処理する方法を指定し、以下の値を処理する。

nil: これは、バッファーを特別な方法で処理しないことを意味する。結果、windowが削除されない場合は、switch-to-prev-bufferの呼び出しにより、通常はそのバッファーが再び表示されるだろう。
append: これは、windowが削除されない場合、そのバッファーをwindowの前のバッファーリストの最後に移動するので、将来のswitch-to-prev-buffer呼び出しでこのバッファーには切り替わることは少なくなる。これは、そのバッファーをフレームのバッファーリストの最後への移動も行う。
bury: これは、windowが削除されない場合、そのバッファーをwindowの前のバッファーリストから削除する。これは、そのバッファーをフレームのバッファーリストの最後への移動も行う。この値は、バッファーをkillすることなくswitch-to-prev-bufferがこのバッファーに再び切り替えさせないようにする、もっとも信頼できる解決手段を提供する。
kill: これは、windowのバッファーをkillすることを意味する。

Typically, the display routines run by display-buffer will set the quit-restore window parameter correctly. It’s also possible to set it manually, using the following code for displaying buffer in window:

(display-buffer-record-window type window buffer)

(set-window-buffer window buffer)

(set-window-prev-buffers window nil)

Setting the window history to nil ensures that a future call to quit-window can delete the window altogether.

以下のオプションは、quitすべきウィンドウ、あるいはバリーすべきバッファーをもつウィンドウを1つだけ含むフレームを処理する方法を指定します。

User Option: frame-auto-hide-function

このオプションで指定された関数は、自動的にフレームを隠すために呼び出される。この関数は、フレームを唯一の引数として呼び出される。

ここで指定される関数は、選択されたウィンドウが専用(dedicated)で、かつバリーされるバッファーを表示しているときに、bury-buffer(バッファーリストを参照)から呼び出される。また、quitされるウィンドウのフレームが、そのウィンドウのバッファーを表示するために特別に作成されたフレームで、かつそのバッファーがkillされないときにも、quit-restore-window(上記)から呼び出される。

The default is to call iconify-frame (see section フレームの可視性). Alternatively, you may specify either delete-frame (see section フレームの削除) to remove the frame from its display, make-frame-invisible to make the frame invisible, ignore to leave the frame unchanged, or any other function that can take a frame as its sole argument.

このオプションで指定された関数は、指定されたフレームが生きたウィンドウただ1つを含み、かつ同一端末上に少なくとも1つ他のフレームが存在する場合のみ呼び出されることに注意。

For a particular frame, the value specified here may be overridden by that frame’s auto-hide-function frame parameter (see section Frame Interaction Parameters).

28.19 Side Windows

Side windows are special windows positioned at any of the four sides of a frame’s root window (see section ウィンドウとフレーム). In practice, this means that the area of the frame’s root window is subdivided into a main window and a number of side windows surrounding that main window. The main window is either a “normal” live window or specifies the area containing all the normal windows.

In their most simple form of use, side windows allow to display specific buffers always in the same area of a frame. Hence they can be regarded as a generalization of the concept provided by display-buffer-at-bottom (see section display-bufferにたいするアクション関数) to the remaining sides of a frame. With suitable customizations, however, side windows can be also used to provide frame layouts similar to those found in so-called integrated development environments (IDEs).

28.19.1 Displaying Buffers in Side Windows

The following action function for display-buffer (see section display-bufferにたいするアクション関数) creates or reuses a side window for displaying the specified buffer.

Function: display-buffer-in-side-window buffer alist

This function displays buffer in a side window of the selected frame. It returns the window used for displaying buffer, nil if no such window can be found or created.

alist is an association list of symbols and values as for display-buffer. The following symbols in alist are special for this function:

side: Denotes the side of the frame where the window shall be located. Valid values are left, top, right and bottom. If unspecified, the window is located at the bottom of the frame.
slot: Denotes a slot at the specified side where to locate the window. A value of zero means to preferably position the window in the middle of the specified side. A negative value means to use a slot preceding (that is, above or on the left of) the middle slot. A positive value means to use a slot following (that is, below or on the right of) the middle slot. Hence, all windows on a specific side are ordered by their slot value. If unspecified, the window is located in the middle of the specified side.

If you specify the same slot on the same side for two or more different buffers, the buffer displayed last is shown in the corresponding window. Hence, slots can be used for sharing the same side window between buffers.

This function installs the window-side and window-slot parameters (see section ウィンドウのパラメーター) and makes them persistent. It does not install any other window parameters unless they have been explicitly provided via a window-parameters entry in alist.

By default, side windows cannot be split via split-window (see section ウィンドウの分割). Also, a side window is not reused or split by any buffer display action (see section display-bufferにたいするアクション関数) unless it is explicitly specified as target of that action. Note also that delete-other-windows cannot make a side window the only window on its frame (see section ウィンドウの削除).

Once set up, side windows also change the behavior of the commands switch-to-prev-buffer and switch-to-next-buffer (see section ウィンドウのヒストリー). In particular, these commands will refrain from showing, in a side window, buffers that have not been displayed in that window before. They will also refrain from having a normal, non-side window show a buffer that has been already displayed in a side window. A notable exception to the latter rule occurs when an application, after displaying a buffer, resets that buffer’s local variables.

28.19.2 Side Window Options and Functions

The following options provide additional control over the placement of side windows.

User Option: window-sides-vertical: If non-nil, the side windows on the left and right of a frame occupy the frame’s full height. Otherwise, the side windows on the top and bottom of the frame occupy the frame’s full width.

User Option: window-sides-slots

This option specifies the maximum number of side windows on each side of a frame. The value is a list of four elements specifying the number of side window slots on (in this order) the left, top, right and bottom of each frame. If an element is a number, it means to display at most that many windows on the corresponding side. If an element is nil, it means there’s no bound on the number of slots on that side.

If any of the specified values is zero, no window can be created on the corresponding side. display-buffer-in-side-window will not signal an error in that case, but will return nil. If a specified value just forbids the creation of an additional side window, the most suitable window on that side is reused and may have its window-slot parameter changed accordingly.

User Option: window-sides-reversed

This option specifies whether top/bottom side windows should appear in reverse order. When this is nil, side windows on the top and bottom of a frame are always drawn from left to right with increasing slot values. When this is t, the drawing order is reversed and side windows on the top and bottom of a frame are drawn from right to left with increasing slot values.

When this is bidi, the drawing order is reversed if and only if the value of bidi-paragraph-direction (see section 双方向テキストの表示) is right-to-left in the buffer displayed in the window most recently selected within the main window area of this frame. Sometimes that window may be hard to find, so heuristics are used to avoid that the drawing order changes inadvertently when another window gets selected.

The layout of side windows on the left or right of a frame is not affected by the value of this variable.

When a frame has side windows, the following function returns the main window of that frame.

Function: window-main-window &optional frame

This function returns the main window of the specified frame. The optional argument frame must be a live frame and defaults to the selected one.

If frame has no side windows, it returns frame’s root window. Otherwise, it returns either an internal non-side window such that all other non-side windows on frame descend from it, or the single live non-side window of frame. Note that the main window of a frame cannot be deleted via delete-window.

The following command is handy to toggle the appearance of all side windows on a specified frame.

Command: window-toggle-side-windows &optional frame

This command toggles side windows on the specified frame. The optional argument frame must be a live frame and defaults to the selected one.

If frame has at least one side window, this command saves the state of frame’s root window in the frame’s window-state frame parameter and deletes all side windows on frame afterwards.

If frame has no side windows, but does have a window-state parameter, this command uses that parameter’s value to restore the side windows on frame leaving frame’s main window alone.

An error is signaled if frame has no side windows and no saved state is found for it.

28.19.3 Frame Layouts with Side Windows

Side windows can be used to create more complex frame layouts like those provided by integrated development environments (IDEs). In such layouts, the area of the main window is where the normal editing activities take place. Side windows are not conceived for editing in the usual sense. Rather, they are supposed to display information complementary to the current editing activity, like lists of files, tags or buffers, help information, search or grep results or shell output.

The layout of such a frame might appear as follows:

     ___________________________________
    |          *Buffer List*            |
    |___________________________________|
    |     |                       |     |
    |  *  |                       |  *  |
    |  d  |                       |  T  |
    |  i  |                       |  a  |
    |  r  |   Main Window Area    |  g  |
    |  e  |                       |  s  |
    |  d  |                       |  *  |
    |  *  |                       |     |
    |_____|_______________________|_____|
    | *help*/*grep*/  |  *shell*/       |
    | *Completions*   |  *compilation*  |
    |_________________|_________________|
    |             Echo Area             |
    |___________________________________|

The following example illustrates how window parameters (see section ウィンドウのパラメーター) can be used with display-buffer-in-side-window (see section Displaying Buffers in Side Windows) to set up code for producing the frame layout sketched above.

(defvar parameters
  '(window-parameters . ((no-other-window . t)
                         (no-delete-other-windows . t))))

(setq fit-window-to-buffer-horizontally t)
(setq window-resize-pixelwise t)

(setq
 display-buffer-alist
 `(("\\*Buffer List\\*" display-buffer-in-side-window
    (side . top) (slot . 0) (window-height . fit-window-to-buffer)
    (preserve-size . (nil . t)) ,parameters)
   ("\\*Tags List\\*" display-buffer-in-side-window
    (side . right) (slot . 0) (window-width . fit-window-to-buffer)
    (preserve-size . (t . nil)) ,parameters)
   ("\\*\\(?:help\\|grep\\|Completions\\)\\*"
    display-buffer-in-side-window
    (side . bottom) (slot . -1) (preserve-size . (nil . t))
    ,parameters)
   ("\\*\\(?:shell\\|compilation\\)\\*" display-buffer-in-side-window
    (side . bottom) (slot . 1) (preserve-size . (nil . t))
    ,parameters)))

This specifies display-buffer-alist entries (see section 表示するウィンドウの選択) for buffers with fixed names. In particular, it asks for showing *Buffer List* with adjustable height at the top of the frame and *Tags List* with adjustable width on the frame’s right. It also asks for having the *help*, *grep* and *Completions* buffers share a window on the bottom left side of the frame and the *shell* and *compilation* buffers appear in a window on the bottom right side of the frame.

Note that the option fit-window-to-buffer-horizontally must have a non-nil value in order to allow horizontal adjustment of windows. Entries are also added that ask for preserving the height of side windows at the top and bottom of the frame and the width of side windows at the left or right of the frame. To assure that side windows retain their respective sizes when maximizing the frame, the variable window-resize-pixelwise is set to a non-nil value. See section ウィンドウのリサイズ.

The last form also makes sure that none of the created side windows are accessible via C-x o by installing the no-other-window parameter for each of these windows. In addition, it makes sure that side windows are not deleted via C-x 1 by installing the no-delete-other-windows parameter for each of these windows.

Since dired buffers have no fixed names, we use a special function dired-default-directory-on-left in order to display a lean directory buffer on the left side of the frame.

(defun dired-default-directory-on-left ()
  "Display `default-directory' in side window on left, hiding details."
  (interactive)
  (let ((buffer (dired-noselect default-directory)))
    (with-current-buffer buffer (dired-hide-details-mode t))
    (display-buffer-in-side-window
     buffer `((side . left) (slot . 0)
              (window-width . fit-window-to-buffer)
              (preserve-size . (t . nil)) ,parameters))))

Evaluating the preceding forms and typing, in any order, M-x list-buffers, C-h f, M-x shell, M-x list-tags, and M-x dired-default-directory-on-left should now reproduce the frame layout sketched above.

28.20 Atomic Windows

Atomic windows are rectangular compositions of at least two live windows. They have the following distinctive characteristics:

The function split-window (see section ウィンドウの分割), when applied to a constituent of an atomic window, will try to create the new window outside of the atomic window.
The function delete-window (see section ウィンドウの削除), when applied to a constituent of an atomic window, will try to delete the entire atomic window instead.
The function delete-other-windows (see section ウィンドウの削除), when applied to a constituent of an atomic window, will try to make the atomic window fill its frame or main window (see section Side Windows).

This means that the basic groups of functions that alter the window structure treat an atomic window like a live one, thus preserving the internal structure of the atomic window.

Atomic windows are useful to construct and preserve window layouts that are meaningful only when all involved buffers are shown simultaneously in a specific manner, such as when showing differences between file revisions, or the same text in different languages or markups. They can also be used to permanently display information pertinent to a specific window in bars on that window’s sides.

Atomic windows are implemented with the help of the reserved window-atom window parameter (see section ウィンドウのパラメーター) and an internal window (see section Emacsウィンドウの基本概念) called the root window of the atomic window. All windows that are part of the same atomic window have this root window as their common ancestor and are assigned a non-nil window-atom parameter.

The following function returns the root of the atomic window a specified window is part of:

Function: window-atom-root &optional window: This functions returns the root of the atomic window window is a part of. The specified window must be a valid window and defaults to the selected one. It returns nil if window is not part of an atomic window.

The most simple approach to make a new atomic window is to take an existing internal window and apply the following function:

Function: window-make-atom window: This function converts window into an atomic window. The specified window must be an internal window. All this function does is to set the window-atom parameter of each descendant of window to t.

To create a new atomic window from an existing live window or to add a new window to an existing atomic window, the following buffer display action function (see section display-bufferにたいするアクション関数) can be used:

Function: display-buffer-in-atom-window buffer alist

This function tries to display buffer in a new window that will be combined with an existing window to form an atomic window. If the existing window is already part of an atomic window, it adds the new window to that atomic window.

The specified alist is an association list of symbols and values. The following symbols have a special meaning:

window: The value of such an element specifies an existing window the new window shall be combined with. If it specifies an internal window, all children of that window become part of the atomic window too. If no window is specified, the new window becomes a sibling of the selected window. The window-atom parameter of the existing window is set to main provided that window is live and its window-atom parameter was not already set.
side: The value of such an element denotes the side of the existing window where the new window shall be located. Valid values are below, right, above and left. The default is below. The window-atom parameter of the new window is set to this value.

The return value is the new window, nil when creating that window failed.

Note that the value of the window-atom parameter does not really matter as long as it is non-nil. The values assigned by display-buffer-in-atom-window just allow for easy retrieval of the original and the new window after that function has been applied. Note also that the window-atom parameter is the only window parameter assigned by display-buffer-in-atom-window. Further parameters have to be set by the application explicitly via a window-parameters entry in alist.

The following code snippet, when applied to a single-window frame, first splits the selected window and makes the selected and the new window constituents of an atomic window with their parent as root. It then displays the buffer *Messages* in a new window at the frame’s bottom and makes that new window part of the atomic window just created.

(let ((window (split-window-right)))
  (window-make-atom (window-parent window))
  (display-buffer-in-atom-window
   (get-buffer-create "*Messages*")
   `((window . ,(window-parent window)) (window-height . 5))))

At this moment typing C-x 2 in any window of that frame produces a new window at the bottom of the frame. Typing C-x 3 instead will put the new window at the frame’s right. In either case, typing now C-x 1 in any window of the atomic window will remove the new window only. Typing C-x 0 in any window of the atomic window will make that new window fill the frame.

28.21 ウィンドウとポイント

それぞれのウィンドウは独自のポイント値(ポイントを参照)をもっており、同じバッファーを表示する他のウィンドウの間でも、それぞれのポイント値は独立しています。これは、1つのバッファーを複数ウィンドウで表示するのに有用です。

ウィンドウポイント(window point)は、ウィンドウが最初に作成されたときに設定される。ウィンドウポイントはバッファーのポイント、またはそのバッファーからオープンされたウィンドウがあればそのウィンドウのウィンドウポイントより初期化される。
ウィンドウ選択により、ウィンドウのポイント値からそのバッファーのポイント値がセットされる。反対に、ウィンドウの非選択により、ウィンドウのポイント値にバッファーのポイント値がセットされる。つまり、与えられたバッファーを表示するウィンドウ間で切り替えを行ったときは、そのバッファーでは選択されたウィンドウのポイント値が効力をもつが、他のウィンドウのポイント値はそのウィンドウに格納される。
選択されたウィンドウがカレントバッファーの表示を続ける限り、そのウィンドウのポイントとバッファーのポイントは常に同時に移動し、等しくあり続ける。

Emacs displays the cursor, by default as a rectangular block, in each window at the position of that window’s point. When the user switches to another buffer in a window, Emacs moves that window’s cursor to where point is in that buffer. If the exact position of point is hidden behind some display element, such as a display string or an image, Emacs displays the cursor immediately before or after that display element.

Function: window-point &optional window

この関数は、window内のカレントのポイント位置をリターンする。選択されていないウィンドウにたいしては、そのウィンドウが選択された場合の、(そのウィンドウのバッファーの)ポイント値である。windowにたいするデフォルトは、選択されたウィンドウである。

When window is the selected window, the value returned is the value of point in that window’s buffer. Strictly speaking, it would be more correct to return the top-level value of point, outside of any save-excursion forms. But that value is hard to find.

Function: set-window-point window position

この関数は、window内のポイントを、windowのバッファー内の位置positionに配置する。リターン値はpositionである。

windowが選択されている場合は、単にwindow内でgoto-charを行う。

Variable: window-point-insertion-type: この変数は、window-pointのマーカー挿入型(Marker 挿入タイプを参照)を指定する。デフォルトはnilで、window-pointは挿入されたテキストの後に留まるだろう。

28.22 ウィンドウの開始位置と終了位置

ウィンドウはそれぞれ、バッファー位置を追跡するために、バッファー内で表示を開始すべき位置を指定するマーカーを保守しています。この位置は、そのウィンドウのdisplay-start(表示開始)、または単にstart(開始)と呼ばれます。この位置の後の文字が、ウィンドウの左上隅に表示される文字となります。これは通常はテキスト行の先頭になりますが、必須ではありません。

ウィンドウやバッファーを切り替えた後、およびいくつかのケースにおいては、ウィンドウが行の途中で開始される場合は、Emacsがィンドウの開始を行の開始に調整します。これは、行中で無意味な位置のウィンドウ開始のまま、特定の操作が行われるのを防ぐためです。この機能は、Lispモードのコマンドを使用して実行することによりある種のLispコードをテストする場合は、それらのコマンドがこの再調整を誘発するために邪魔になるかもしれません。そのようなコードをテストするためには、それをコマンド内に記述して、何らかのキーにバインドしてください。

Function: window-start &optional window

この関数は、ウィンドウwindowの表示開始位置をリターンする。windowがnilなら、選択されたウィンドウが使用される。

ウィンドウを作成したり、他のバッファーをウィンドウ内に表示する際、display-start位置は同じバッファーにたいしてもっとも最近に使用されたdisplay-start位置か、そのバッファーがそれをもたなければpoint-minにセットされる。

ポイントがスクリーン上に確実に現れるように、再表示はwindow-start位置を更新する(前の再表示以降にwindow-start位置を明示的に指定していない場合)。再表示以外に、window-start位置を自動的に変更するものはない。ポイントを移動した場合は、次の再表示後までポイントの移動に応じてwindow-startが変更されるのを期待してはならない。

Function: window-group-start &optional window: This function is like window-start, except that when window is a part of a group of windows (see Window Group), window-group-start returns the start position of the entire group. This condition holds when the buffer local variable window-group-start-function is set to a function. In this case, window-group-start calls the function with the single argument window, then returns its result.

Function: window-end &optional window update

この関数は、windowのバッファーの最後を表示する位置をリターンする。windowにたいするデフォルトは、選択されたウィンドウである。

バッファーテキストの単なる変更やポイントの移動では、window-endがリターンする値は更新されない。この値は、Emacsが再表示を行い、それが妨害されることなく再表示が完了したときのみ更新される。

windowの最後の再表示が妨害されて完了しなかった場合、Emacsはそのウィンドウ内の表示のend位置を知らない。この場合、関数はnilをリターンする。

updateが非nilの場合、window-endはwindow-startのカレント値にもとづき、どこが表示のendかにたいして最新の値をリターンする。以前に保存された位置の値がまだ有効なら、window-endはその値をリターンする。それ以外は、バッファーのテキストをスキャンして、正しい値を計算する。

たとえupdateが非nilでも、window-endはポイントが画面外に移動していても、実際の再表示が行うような表示のスクロールを試みない。これは、window-startの値を変更しない。これは実際には、スクロールが要求されない場合の表示されたテキストのendがどこかを報告する。

Function: window-group-end &optional window update: This function is like window-end, except that when window is a part of a group of windows (see Window Group), window-group-end returns the end position of the entire group. This condition holds when the buffer local variable window-group-end-function is set to a function. In this case, window-group-end calls the function with the two arguments window and update, then returns its result. The argument update has the same meaning as in window-end.

Function: set-window-start window position &optional noforce

この関数は、windowのdisplay-start位置を、windowのバッファーのpositionにセットする。リターン値は、positionである。

表示ルーチンは、バッファーが表示されたときに、ポイント位置が可視になることを強要する。通常これらは、ポイントを可視にするために必要なときは常に、display-start位置を変更(つまりウィンドウをスクロール)する。しかし、この関数でnoforceにnilを使用してstart位置を指定した場合は、たとえポイントを画面外になるような場所に配したとしても、positionでの表示開始を望んでいることを意味する。これによりポイントが画面外に配された場合、表示ルーチンはポイントをウィンドウ内の中央行の左マージンに移動する。

For example, if point is 1 and you set the start of the window to 37, the start of the next line, point will be above the top of the window. The display routines will automatically move point if it is still 1 when redisplay occurs. Here is an example:

;; 以下は式set-window-start実行前
;;   ‘foo’の様子である

---------- Buffer: foo ----------
∗This is the contents of buffer foo.
2
3
4
5
6
---------- Buffer: foo ----------

(set-window-start
 (selected-window)
 (save-excursion
   (goto-char 1)
   (forward-line 1)
   (point)))
⇒ 37

;; 以下は式set-window-start実行後の
;;   ‘foo’の様子である
---------- Buffer: foo ----------
2
3
∗4
5
6
---------- Buffer: foo ----------

noforceが非nilで、かつ次回の再表示でポイントが画面外に配される場合、再表示はポイントと協調して機能する位置となるような新たなwindow-startを計算するので、positionは使用されない。

Function: set-window-group-start window position &optional noforce: This function is like set-window-start, except that when window is a part of a group of windows (see Window Group), set-window-group-start sets the start position of the entire group. This condition holds when the buffer local variable set-window-group-start-function is set to a function. In this case, set-window-group-start calls the function with the three arguments window, position, and noforce, then returns its result. The arguments position and noforce in this function have the same meaning as in set-window-start.

Function: pos-visible-in-window-p &optional position window partially

This function returns non-nil if position is within the range of text currently visible on the screen in window. It returns nil if position is scrolled vertically out of view. Locations that are partially obscured are not considered visible unless partially is non-nil. The argument position defaults to the current position of point in window; window defaults to the selected window. If position is t, that means to check either the first visible position of the last screen line in window, or the end-of-buffer position, whichever comes first.

この関数は、垂直スクロールだけを考慮する。 This function considers only vertical scrolling. windowが水平にスクロールされたことだけの理由でpositionが表示範囲外の場合は、いずれにせよpos-visible-in-window-pは非nilをリターンする。水平スクロールを参照のこと。

positionが可視でpartiallyがnilなら、pos-visible-in-window-pはtをリターンする。partiallyが非nilでposition以降の文字が完全に可視の場合は、(x y)という形式のリストをリターンする。ここでxとyは、ウィンドウの左上隅からの相対的なピクセル座標である。position以降の文字が完全に可視ではない場合は、拡張された形式のリスト(x y rtop rbot rowh vpos)をリターンする。ここでrtopとrbotはpositionでウィンドウ外となった上端と下端のピクセル数、rowhはその行の可視な部分の高さ、vposはその行の垂直位置(0基準の行番号)を指定する。

以下に例を示す:

;; ポイントが画面外ならrecenterする
(or (pos-visible-in-window-p
     (point) (selected-window))
    (recenter 0))

Function: pos-visible-in-window-group-p &optional position window partially: This function is like pos-visible-in-window-p, except that when window is a part of a group of windows (see Window Group), pos-visible-in-window-group-p tests the visibility of pos in the entire group, not just in the single window. This condition holds when the buffer local variable pos-visible-in-window-group-p-function is set to a function. In this case pos-visible-in-window-group-p calls the function with the three arguments position, window, and partially, then returns its result. The arguments position and partially have the same meaning as in pos-visible-in-window-p.

Function: window-line-height &optional line window

この関数は、window内のテキスト行lineの高さをリターンする。lineがheader-line、mode-line、window-line-heightのいずれかの場合は、そのウィンドウの対応する行についての情報をリターンする。それ以外では、lineは0から始まるテキスト行番号である。負数の場合は、そのウィンドウのendから数える。lineにたいするデフォルトは、window内のカレント行、windowにたいするデフォルトは、選択されたウィンドウである。

表示が最新でなければ、window-line-heightはnilをリターンする。その場合は、関連する情報を入手するために、pos-visible-in-window-pを使用できる。

指定されたlineに対応する行がなければ、window-line-heightはnilをリターンする。それ以外では、リスト(height vpos ypos offbot)をリターンする。ここでheightはその行の可視部分のピクセル高さ、vposとyposは最初のテキスト行上端からのその行への相対的な垂直位置の行数とピクセル数、offbotはそのテキスト行下端のウィンドウ外のピクセル数である。(最初の)テキスト行上端にウィンドウ外のピクセルがある場合、yposは負となる。

28.23 テキスト的なスクロール

テキスト的なスクロール(textual scrolling)とは、ウィンドウ内のテキストを上や下に移動することを意味します。これは、そのウィンドウのdisplay-startを変更することにより機能します。これは、ポイントを画面上に維持するために、window-pointの値も変更するかもしれません(ウィンドウとポイントを参照)。

テキスト的なスクロールの基本的な関数は、(前方にスクロールする)scroll-upと、(後方にスクロールする)scroll-downです。これらの関数の名前における“up”と“down”は、バッファーテキストのそのウィンドウにたいする相対的な移動方向を示します。そのテキストが長いロール紙に記述されていて、スクロールコマンドはその上を上下に移動すると想像してみてください。つまり、バッファーの中央に注目している場合、繰り返してscroll-downを呼び出すと、最終的にはバッファーの先頭を目にすることになるでしょう。

残念なことに、これは時折混乱を招きます。なぜなら、ある人はこれを逆の慣習にもとづいて考える傾向があるからです。彼らは、テキストがその場所に留まりウィンドウが移動して、“down”コマンドによりバッファー終端に移動するだろうと想像します。この慣習は、そのようなコマンドが現代風のキーボード上のPageDownという名前のキーにバインドされているという事実と一致しています。

選択されたウィンドウ内で表示されているバッファーがカレントバッファーでない場合、(scroll-other-window以外の)テキスト的スクロール関数の結果は予測できません。カレントバッファーを参照してください。

(たとえば大きなイメージがある等で)ウィンドウにウィンドウの高さより高い行が含まれる場合、スクロール関数は部分的に可視な行をスクロールするために、そのウィンドウの垂直スクロール位置を調整します。Lisp呼び出し側は、変数auto-window-vscrollをnilにバインドすることにより、この機能を無効にできます(割り合いによる垂直スクロールを参照)。

Command: scroll-up &optional count

この関数は、選択されたウィンドウ内でcount行前方にスクロールする。

count負の場合は、かわりに後方へスクロールする。countがnil(または省略)の場合、スクロールされる距離は、そのウィンドウのテキストエリアの高さより小さいnext-screen-context-linesとなる。

選択されたウィンドウがそれ以上スクロールできない場合、この関数はエラーをシグナルし、それ以外はnilをリターンする。

Command: scroll-down &optional count

この関数は、選択されたウィンドウ内でcount行後方にスクロールする。

count負の場合は、かわりに後方へスクロールする。それ以外の点では、これはscroll-upが行うのと同様に振る舞う。

Command: scroll-up-command &optional count: これはscroll-upと同様に振る舞うが、選択されたウィンドウがそれ以上スクロールできず、かつ変数scroll-error-top-bottomの値がtの場合は、かわりにそのバッファーの終端への移動を試みる。ポイントがすでに終端にある場合は、エラーをシグナルする。

Command: scroll-down-command &optional count: これはscroll-downと同様に振る舞うが、選択されたウィンドウがそれ以上スクロールできず、かつ変数scroll-error-top-bottomの値がtの場合は、かわりにそのバッファーの先頭への移動を試みる。ポイントがすでに先頭にある場合は、エラーをシグナルする。

Command: scroll-other-window &optional count

この関数は、他のウィンドウ内のテキストを上方にcount行スクロールする。countが負、またはnilの場合は、scroll-upのように処理される。

変数other-window-scroll-bufferにバッファーをセットすることにより、どのバッファーをスクロールするかを指定できる。そのバッファーが表示されていない場合、scroll-other-windowはそれを何らかのウィンドウに表示する、

選択されたウィンドウがミニバッファーのとき、次ウィンドウは通常はそのウィンドウの直上最左のウィンドウである。変数minibuffer-scroll-windowをセットすることにより、スクロールする別のウィンドウを指定できる。この変数は、ミニバッファー以外のウィンドウが選択されているときは効果がない。これが非nilで、かつミニバッファーが選択されているとき、これはother-window-scroll-bufferより優先される。Definition of minibuffer-scroll-windowを参照のこと。

ミニバッファーがアクティブのとき、選択されたウィンドウが下端右角のウィンドウなら、ミニバッファーが次ウィンドウになる。この場合、scroll-other-windowはミニバッファーのスクロールを試みる。ミニバッファーに含まれるのが1行だけの場合はどこにもスクロールできないので、エコーエリアに瞬時メッセージ‘End of buffer’を表示後、その行を再表示する。

Variable: other-window-scroll-buffer: この変数が非nilなら、それはscroll-other-windowがどのバッファーのウィンドウをスクロールするかを指定する。

User Option: scroll-margin: このオプションは、スクロールマージン(ポイントとウィンドウの上端/下端との最小行数)のサイズを指定する。ポイントがウィンドウの上端/下端からその行数になったとき、再表示は(可能なら)ポイントをそのマージン外、ウィンドウの中央付近に移動するために、テキストを自動的にスクロールする。

User Option: maximum-scroll-margin

This variable limits the effective value of scroll-margin to a fraction of the current window line height. For example, if the current window has 20 lines and maximum-scroll-margin is 0.1, then the scroll margins will never be larger than 2 lines, no matter how big scroll-margin is.

maximum-scroll-margin itself has a maximum value of 0.5, which allows setting margins large to keep the cursor at the middle line of the window (or two middle lines if the window has an even number of lines). If it’s set to a larger value (or any value other than a float between 0.0 and 0.5) then the default value of 0.25 will be used instead.

User Option: scroll-conservatively

この変数は、ポイントがスクリーン外(またはスクロールマージン内)に移動したとき、スクロールを自動的に行う方法を指定する。値が正の整数nの場合、再表示はそれが正しい表示範囲内にポイントを戻すなら、いずれかの方向にn行以下のテキストをスクロールする。この振る舞いは、保守的なスクロール(conservative scrolling)と呼ばれる。それ以外の場合、スクロールはscroll-up-aggressivelyやscroll-down-aggressivelyのような他の変数の制御の下、通常の方法で発生する。

デフォルトの値は0で、これは保守的スクロールが発生し得ないことを意味する。

User Option: scroll-down-aggressively

この変数の値は、nilか、0から1までの小数fであること。これが小数なら、スクリーン上でポイントが置かれたとき、下にスクロールする場所を指定する。より正確には、ポイントがウィンドウstartより上という理由によりウィンドウが下にスクロールされるとき、新たなstart位置はウィンドウ上端からウィンドウ高さのfの箇所にポイントが置かれるように選択される。より大きなfでは、よりaggressive(積極的)にスクロールする。

ポイントを中央に配すのがその効果なので、値nilは.5と等価である。どのような方法によりセットされたときでも、この変数は自動的にバッファーローカルになる。

User Option: scroll-up-aggressively: scroll-up-aggressivelyと同様。値fは、ポイントがウィンドウ下端からどれほどの位置に置かれるべきかを指定する。つまり、scroll-up-aggressivelyと同様、大きな値ｄｗはよりaggressive(積極的)になる。

User Option: scroll-step: この変数は、scroll-conservativelyのより古い変種である。違いは、値がnならn以下の値ではなく、正確にnだけのスクロールを許容することである。この機能は、scroll-marginとは共に機能しない。デフォルトは0。

User Option: scroll-preserve-screen-position

このオプションがtなら、スクロールによりポイントがウィンドウ外に移動したとき、Emacsは常に、ポイントがポイントの上下端ではなくカーソルがそのウィンドウ内の元の垂直位置に保たれるようポイントの調整を試みる。

値が非nilかつ非tの場合、たとえスクロールコマンドによりポイントがウィンドウ外に移動していなくとも、Emacsはカーソルが同じ垂直位置に保たれるよう、ポイントを調整する。

このオプションはシンボルプロパティscroll-commandが非nilであるような、すべてのスクロールコマンドに影響する。

User Option: next-screen-context-lines: この変数の値は、全画面スクロールされたときに残される継続される行数を指定する。たとえば、引数がnilのscroll-upは、ウィンドウ上端ではなく下端に残される行数でスクロールする。デフォルト値は2。

User Option: scroll-error-top-bottom

このオプションがnil(デフォルト)の場合、それ以上のスクロールが不可能な際に、scroll-up-commandとscroll-down-commandは単にエラーをシグナルする。

値がtなら、これらのコマンドはかわりにポイントをバッファーの先頭か終端(スクロール方向に依存する)に移動する。ポイントがすでにその位置にある場合のみ、エラーをシグナルする。

Command: recenter &optional count

This function scrolls the text in the selected window so that point is displayed at a specified vertical position within the window. It does not move point with respect to the text.

countが非負の数の場合は、そのウィンドウ上端からcount行下にポイントを含む行を配す。countが負なら、ウィンドウ下端から上に数えるので、-1はそのウィンドウ内で最後の利用可能な行となる。

countがnil(または非nilのリスト)の場合、recenterはポイントを含む行をウィンドウの中央に配す。countがnilなら、この関数はrecenter-redisplayの値に応じて、フレームを再描画するかもしれない。

recenterがインタラクティブに呼び出されたときは、rawプレフィックス引数がcountとなる。したがって、プレフィックスとしてC-uをタイプするとcountに非nil、C-u 4ではcountに4がセットされ、後者ではカレント行を上端から4行目にセットする。

引数0では、recenterはカレント行をウィンドウ上端に配す。コマンドrecenter-top-bottomは、これを達成するためにより簡便な方法を提供する。

Function: recenter-window-group &optional count: This function is like recenter, except that when the selected window is part of a group of windows (see Window Group), recenter-window-group scrolls the entire group. This condition holds when the buffer local variable recenter-window-group-function is set to a function. In this case, recenter-window-group calls the function with the argument count, then returns its result. The argument count has the same meaning as in recenter, but with respect to the entire window group.

User Option: recenter-redisplay: この変数が非nilの場合は、引数nilでrecenterを呼び出すことにより、フレームを再描画する。デフォルト値はttyで、これはフレームがttyフレームのときだけフレームを再描画することを意味する。

Command: recenter-top-bottom &optional count: デフォルトではC-lにバインドされているこのコマンドは、recenterと同様に動作するが、引数なしで呼び出されたときの動作が異なる。この場合、連続して呼び出すことにより、変数recenter-positionsで定義されるサイクル順に応じてポイントを配する。

User Option: recenter-positions: これは、recenter-top-bottomを引数なしで呼び出したときの挙動を制御する。デフォルト値は(middle top bottom)で、これは引数なしでrecenter-top-bottomを連続して呼び出すと、ポイントをウィンドウの中央、上端、下端と巡回して配すことを意味する。

28.24 割り合いによる垂直スクロール

垂直フラクショナルスクロール(vertical fractional scrolling)とは、指定された値を行に乗ずるることによりウィンドウ内のテキストを上下にシフトすることを意味します。ウィンドウはそれぞれ、決して0より小さくなることはない、垂直スクロール位置(vertical scroll position)という数値をもっています。これは、ウィンドウのコンテンツをどこから表示開始(raise)するかを指定します。ウィンドウのコンテンツの表示開始により、一般的には上端の何行かのすべて、または一部が表示されなくなり、他の何行かのすべて、または一部が下端に表示されるようになります。通常の値は0です。

垂直スクロール位置は、通常行の高さ(デフォルトフォントの高さ)の単位で数えられます。したがって、値が.5なら、それはウィンドウのコンテンツが、通常行の半分の高さで上にスクロールされていることを、3.3なら通常行の3倍を若干超える高さで上にスクロールされていることを意味します。

垂直スクロールが覆い隠す(cover)のがどれほどの行断片(fraction of a line)、あるいは行数かは、それらの行に何が含まれるかに依存します。3.3という値が高さが高い行やイメージの一部だけを画面外にスクロールできることもあれば、.5という値が非常に低い高さの行を画面外にスクロールできることもあります。

Function: window-vscroll &optional window pixels-p

この関数は、windowのカレントの垂直スクロール位置をリターンする。windowのデフォルトは、選択されたウィンドウである。pixels-pが非nilの場合、リターン値は通常行高さ単位ではなく、ピクセル単位で測定される。

(window-vscroll)
     ⇒ 0

Function: set-window-vscroll window lines &optional pixels-p

この関数は、windowの垂直スクロール位置をlinesにセットする。windowがnilなら、選択されたウィンドウが使用される。引数linesは0または正であること。それ以外は0として扱われる。

実際の垂直スクロール位置は、常にピクセルの整数に対応しなければならないため、指定した値はそれに応じて丸められる。

こも丸め結果がリターン値となる。

(set-window-vscroll (selected-window) 1.2)
     ⇒ 1.13

pixels-pが非nilの場合、linesはピクセル数を指定する。この場合、リターン値はlinesである。

Variable: auto-window-vscroll: この変数が非nilなら、関数line-move、scroll-up、scroll-downは、たとえば大きなイメージが存在する等でウィンドウ高さより高いディスプレイ行をスクロールするために、垂直スクロール位置を自動的に変更するだろう。

28.25 水平スクロール

水平スクロール(horizontal scrolling)とは、指定された通常文字幅の倍数でウィンドウ内のイメージを左右にシフトすることを意味します。ウィンドウはそれぞれ、決して0より小さくなることはない、水平スクロール位置(horizontal scroll position)という数値をもっています。これは、コンテンツをどれほど左にシフトするかを指定します。ウィンドウのコンテンツを左にシフトすることにより、一般的には左にある文字のすべて、または一部が表示されなくなり、右にある文字のすべて、または一部が表示されることを意味します。通常の値は0です。

水平スクロール位置は、通常文字幅を単位として数えられます。したがって値が5なら、それはウィンドウのコンテンツは通常文字幅の5倍左にスクロールされることを意味します。左の何文字が表示されなくなるかは、それらの文字の文字幅とに依存しており、行ごとに異なります。

Because we read from side to side in the inner loop, and from top to bottom in the outer loop, the effect of horizontal scrolling is not like that of textual or vertical scrolling. Textual scrolling involves selection of a portion of text to display, and vertical scrolling moves the window contents contiguously; but horizontal scrolling causes part of each line to go off screen.

通常は、水平スクロールは行われないので、ウィンドウ左端には最左列があります。この状態では、右スクロールにより左端に新たに表示されるデータは存在しないので、右へのスクロールはできません。左スクロールにより、テキストの1列目がウィンドウ端からウィンドウ外にスクロールされ、右端にはその前は切り詰められていた(truncated)列が新たに表示されるので、左へのスクロールはできます。ウィンドウが左へ非0の量を水平スクロールされていれば、右スクロールしてそれを戻すことができますが、正味の水平スクロールが0に減少するまでの間のみ、右スクロールができます。左へどれほどスクロールできるかに制限はありませんが、最終的にはすべてのテキストが左端の外に消えるでしょう。

auto-hscroll-modeがセットされている場合、再表示はポイントが常に可視となることを保証するために、必要に応じて水平スクロールを自動的に変更する。とはいえ、依然として水平スクロール位置を明示的に指定するのは可能である。指定した値は、自動スクロールの下限値としての役目を果たす(自動スクロールは指定された値より小さい列にウィンドウをスクロールしない)。

The default value of auto-hscroll-mode is t; setting it to current-line activates a variant of automatic horizontal scrolling whereby only the line showing the cursor is horizontally scrolled to make point visible, the rest of the window is left either unscrolled, or at the minimum scroll amount set by scroll-left and scroll-right, see below.

Command: scroll-left &optional count set-minimum

この関数は、選択されたウィンドウを左(countが負なら右)にcount列スクロールする。countのデフォルトはウィンドウ幅から2を減じた値である。

リターン値は、window-hscroll(以下参照)がリターンする値と同様、変更後に実際に左に水平スクロールされたトータル量である。

Note that text in paragraphs whose base direction is right-to-left (see section 双方向テキストの表示) moves in the opposite direction: e.g., it moves to the right when scroll-left is invoked with a positive value of count.

ウィンドウを可能な限り右にスクロールした後は、左スクロールの合計が0であるような通常の位置に戻り、右へのそれ以上のスクロールの試みは効果をもたない。

set-minimumが非nilの場合、新たなスクロール量は自動スクロールの下限値となる。つまり自動スクロールは、この関数がリターンする値より小さい列にウィンドウをスクロールしないだろう。インタラクティブに呼び出すと、set-minimumに非nilを渡す。

Command: scroll-right &optional count set-minimum: この関数は、選択されたウィンドウを右(countが負なら左)にcount列スクロールする。countのデフォルトはウィンドウ幅から2を減じた値である。スクロール方向を除けば、これはscroll-leftと同様に機能する。

Function: window-hscroll &optional window

This function returns the total leftward horizontal scrolling of window—the number of columns by which the text in window is scrolled left past the left margin. (In right-to-left paragraphs, the value is the total amount of the rightward scrolling instead.) The default for window is the selected window.

リターン値が負になることは決してない。windowで水平スクロールが行われていない場合(これが通常)、リターン値は0である。

(window-hscroll)
     ⇒ 0

(scroll-left 5)
     ⇒ 5

(window-hscroll)
     ⇒ 5

Function: set-window-hscroll window columns

This function sets horizontal scrolling of window. The value of columns specifies the amount of scrolling, in terms of columns from the left margin (right margin in right-to-left paragraphs). The argument columns should be zero or positive; if not, it is taken as zero. Fractional values of columns are not supported at present.

シンプルにM-:を呼び出して評価する方法でテストした場合は、set-window-hscrollが機能していないように見えるかもしれないことに注意されたい。何が発生しているかというと、この関数は水平スクロール値をセットしてリターンするが、その後にポイントを可視にするために水平スクロールを調整するよう再表示が行なわれ、これが関数の行った処理をオーバーライドしている。この関数の効果は、左マージンからポイントまでのスクロール量が、ポイントが可視のまま留まるように関数を呼び出すことにより観察できる。

リターン値はcolumnsである。

(set-window-hscroll (selected-window) 10)
     ⇒ 10

以下は、与えられた位置positionが水平スクロールによりスクリーン外にあるかどうかを判断する例です:

(defun hscroll-on-screen (window position)
  (save-excursion
    (goto-char position)
    (and
     (>= (- (current-column) (window-hscroll window)) 0)
     (< (- (current-column) (window-hscroll window))
        (window-width window)))))

28.26 座標とウィンドウ

This section describes functions that report positions of and within a window. Most of these functions report positions relative to an origin at the native position of the window’s frame (see section Frame Geometry). Some functions report positions relative to the origin of the display of the window’s frame. In any case, the origin has the coordinates (0, 0) and X and Y coordinates increase rightward and downward respectively.

For the following functions, X and Y coordinates are reported in integer character units, i.e., numbers of lines and columns respectively. On a graphical display, each “line” and “column” corresponds to the height and width of the default character specified by the frame’s default font (see section Frame Font).

Function: window-edges &optional window body absolute pixelwise

この関数は、window端の座標のリストをリターンする。If windowが省略またはnilの場合のデフォルトは、選択されたウィンドウである。

リターン値は、(left top right bottom)という形式をもつ。リストの要素は順に、そのウィンドウにより占有される最左列のX座標、最上行のY座標、最右列より1列右のX座標、最下行より1行下のY座標である。

これらは、ヘッダーライン、モードライン、スクロールバー、ウィンドウディバイダー、ディスプレイマージンを含む、ウィンドウの実際の外端であることに注意。テキスト端末では、そのウィンドウの右に隣接するウィンドウがある場合、ウィンドウの右端にはそのウィンドウと隣接するウィンドウの間のセパレーターラインが含まれる。

If the optional argument body is nil, this means to return the edges corresponding to the total size of window. body non-nil means to return the edges of window’s body (aka text area). If body is non-nil, window must specify a live window.

If the optional argument absolute is nil, this means to return edges relative to the native position of window’s frame. absolute non-nil means to return coordinates relative to the origin (0, 0) of window’s display. On non-graphical systems this argument has no effect.

If the optional argument pixelwise is nil, this means to return the coordinates in terms of the default character width and height of window’s frame (see section Frame Font), rounded if necessary. pixelwise non-nil means to return the coordinates in pixels. Note that the pixel specified by right and bottom is immediately outside of these edges. If absolute is non-nil, pixelwise is implicitly non-nil too.

Function: window-body-edges &optional window: This function returns the edges of window’s body (see section ウィンドウのサイズ). Calling (window-body-edges window) is equivalent to calling (window-edges window t), see above.

以下の関数は、フレーム相対座標(frame-relative coordinates)のセットからウィンドウへの関連付けに使用できます:

Function: window-at x y &optional frame

This function returns the live window at the coordinates x and y given in default character sizes (see section Frame Font) relative to the native position of frame (see section Frame Geometry).

If there is no window at that position, the return value is nil. If frame is omitted or nil, it defaults to the selected frame.

Function: coordinates-in-window-p coordinates window

This function checks whether a window window occupies the frame relative coordinates coordinates, and if so, which part of the window that is. window should be a live window.

coordinates should be a cons cell of the form (x . y), where x and y are given in default character sizes (see section Frame Font) relative to the native position of window’s frame (see section Frame Geometry).

指定された位置にウィンドウが存在しない場合、リターン値はnilである。それ以外では、リターン値は以下のいずれかになる:

(relx . rely): その座標はwindow内にある。数値relxとrelyは、指定された位置にたいするウィンドウ左上隅を原点に0から数えたウィンドウ相対座標と等価である。
mode-line: その座標はwindowのモードライン内にある。
header-line: その座標はwindowのヘッダーライン内にある。
right-divider: その座標はwindowと右に隣接するウィンドウを分けるディバイダー内にある。
bottom-divider: その座標はwindowと下にあるウィンドウを分けるディバイダー内にある。
vertical-line: その座標はwindowと右に隣接するウィンドウを分ける垂直ライン内にある。この値は、ウィンドウにスクロールバーがないときのみ発生し得る。スクロールバー内の位置は、これらの目的にたいしてはウィンドウ外と判断される。
left-fringe
right-fringe: その座標はウィンドウの左か右のフリンジ内にある。
left-margin
right-margin: その座標はウィンドウの左か右のマージン内にある。
nil: その座標は、windowのいずれの部分でもない。

関数coordinates-in-window-pはwindowのあるフレームを使用するので、引数としてフレームを要求しない。

The following functions return window positions in pixels, rather than character units. Though mostly useful on graphical displays, they can also be called on text terminals, where the screen area of each text character is taken to be one pixel.

Function: window-pixel-edges &optional window: This function returns a list of pixel coordinates for the edges of window. Calling (window-pixel-edges window) is equivalent to calling (window-edges window nil nil t), see above.

Function: window-body-pixel-edges &optional window: This function returns the pixel edges of window’s body. Calling (window-body-pixel-edges window) is equivalent to calling (window-edges window t nil t), see above.

The following functions return window positions in pixels, relative to the origin of the display screen rather than that of the frame:

Function: window-absolute-pixel-edges &optional window: This function returns the pixel coordinates of window relative to an origin at (0, 0) of the display of window’s frame. Calling (window-absolute-pixel-edges) is equivalent to calling (window-edges window nil t t), see above.

Function: window-absolute-body-pixel-edges &optional window

This function returns the pixel coordinates of window’s body relative to an origin at (0, 0) of the display of window’s frame. Calling (window-absolute-body-pixel-edges window) is equivalent to calling (window-edges window t t t), see above.

Combined with set-mouse-absolute-pixel-position, this function can be used to move the mouse pointer to an arbitrary buffer position visible in some window:

(let ((edges (window-absolute-body-pixel-edges))
      (position (pos-visible-in-window-p nil nil t)))
  (set-mouse-absolute-pixel-position
   (+ (nth 0 edges) (nth 0 position))
   (+ (nth 1 edges) (nth 1 position))))

On a graphical terminal this form “warps” the mouse cursor to the upper left corner of the glyph at the selected window’s point. A position calculated this way can be also used to show a tooltip window there.

The following function returns the screen coordinates of a buffer position visible in a window:

Function: window-absolute-pixel-position &optional position window

If the buffer position position is visible in window window, this function returns the display coordinates of the upper/left corner of the glyph at position. The return value is a cons of the X- and Y-coordinates of that corner, relative to an origin at (0, 0) of window’s display. It returns nil if position is not visible in window.

window must be a live window and defaults to the selected window. position defaults to the value of window-point of window.

This means that in order to move the mouse pointer to the position of point in the selected window, it’s sufficient to write:

(let ((position (window-absolute-pixel-position)))
  (set-mouse-absolute-pixel-position
   (car position) (cdr position)))

The following function returns the largest rectangle that can be inscribed in a window without covering text displayed in that window.

Function: window-largest-empty-rectangle &optional window count min-width min-height positions left

This function calculates the dimensions of the largest empty rectangle that can be inscribed in the specified window’s text area. window must be a live window and defaults to the selected one.

The return value is a triple of the width and the start and end y-coordinates of the largest rectangle that can be inscribed into the empty space (space not displaying any text) of the text area of window. No x-coordinates are returned by this function—any such rectangle is assumed to end at the right edge of window’s text area. If no empty space can be found, the return value is nil.

The optional argument count, if non-nil, specifies a maximum number of rectangles to return. This means that the return value is a list of triples specifying rectangles with the largest rectangle first. count can be also a cons cell whose car specifies the number of rectangles to return and whose CDR, if non-nil, states that all rectangles returned must be disjoint.

The optional arguments min-width and min-height, if non-nil, specify the minimum width and height of any rectangle returned.

The optional argument positions, if non-nil, is a cons cell whose CAR specifies the uppermost and whose CDR specifies the lowermost pixel position that must be covered by any rectangle returned. These positions measure from the start of the text area of window.

The optional argument left, if non-nil, means to return values suitable for buffers displaying right to left text. In that case, any rectangle returned is assumed to start at the left edge of window’s text area.

Note that this function has to retrieve the dimensions of each line of window’s glyph matrix via window-lines-pixel-dimensions (see section 表示されるテキストのサイズ). Hence, this function may also return nil when the current glyph matrix of window is not up-to-date.

28.27 Mouse Window Auto-selection

The following option allows to automatically select the window under the mouse pointer. This accomplishes a policy similar to that of window managers that give focus to a frame (and thus trigger its subsequent selection) whenever the mouse pointer enters its window-system window (see section 入力のフォーカス).

User Option: mouse-autoselect-window

If this variable is non-nil, Emacs will try to automatically select the window under the mouse pointer. The following values are meaningful:

A positive number: This specifies a delay in seconds after which auto-selection triggers. The window under the mouse pointer is selected after the mouse has remained in it for the entire duration of the delay.
A negative number: A negative number has a similar effect as a positive number, but selects the window under the mouse pointer only after the mouse pointer has remained in it for the entire duration of the absolute value of that number and in addition has stopped moving.
Other value: Any other non-nil value means to select a window instantaneously as soon as the mouse pointer enters it.

In either case, the mouse pointer must enter the text area of a window in order to trigger its selection. Dragging the scroll bar slider or the mode line of a window conceptually should not cause its auto-selection.

Mouse auto-selection selects the minibuffer window only if it is active, and never deselects the active minibuffer window.

Mouse auto-selection can be used to emulate a focus follows mouse policy for child frames (see section Child Frames) which usually are not tracked by the window manager. This requires to set the value of focus-follows-mouse (see section 入力のフォーカス) to a non-nil value. If the value of focus-follows-mouse is auto-raise, entering a child frame with the mouse will raise it automatically above all other child frames of that frame’s parent frame.

28.28 ウィンドウの構成

A window configuration records the entire layout of one frame—all windows, their sizes, which buffers they contain, how those buffers are scrolled, and their value of point; also their fringes, margins, and scroll bar settings. It also includes the value of minibuffer-scroll-window. As a special exception, the window configuration does not record the value of point in the selected window for the current buffer.

以前に保存されたウィンドウ構成をリストアすることにより、フレーム全体のレイアウトを取り戻すことができます。1つだけではなくすべてのフレームのレイアウトを記録したい場合は、ウィンドウ構成のかわりに、フレーム構成(frame configuration)を使用します。フレーム構成を参照してください。

Function: current-window-configuration &optional frame: この関数は、frameのカレントのウィンドウ構成を表す新たなオブジェクトをリターンする。frameのデフォルトは選択されたフレームである。変数window-persistent-parametersは、この関数により保存されるウィンドウパラメーター(もしあれば)を指定する。ウィンドウのパラメーターを参照のこと。

Function: set-window-configuration configuration

この関数は、configurationが作成されたフレームにたいして、ウィンドウとバッファーの構成をconfigurationで指定された構成にリストアする。

The argument configuration must be a value that was previously returned by current-window-configuration. The configuration is restored in the frame from which configuration was made, whether that frame is selected or not. In some rare cases this may trigger execution of the window-size-change-functions (see section ウィンドウのスクロールと変更のためのフック) even if the size of windows did not change at all. The window-configuration-change-hook functions will be called if and only if at least one window was added to or deleted from the frame.

configurationが保存されたフレームが死んでいる(生きていない)場合、この関数が行うのは3つの変数window-min-height、window-min-width、minibuffer-scroll-windowのリストアだけである。この場合、関数はnilをリターンし、それ以外はtをリターンする。

以下は、save-window-excursionと同様な効果を得るためにこの関数を使用する例である:

(let ((config (current-window-configuration)))
  (unwind-protect
      (progn (split-window-below nil)
             …)
    (set-window-configuration config)))

Macro: save-window-excursion forms…

このマクロは、選択されたフレームのウィンドウ構成を記録して、formsを順に実行してから、以前のウィンドウ構成をリストアする。リターン値は、forms内の最後のフォームの値である。

Lispコードのほとんどは、このマクロを使用すべきではない。大抵はsave-selected-windowで十分である。特に、このマクロはforms内で新たなウィンドウをオープンするコードを確実に防ぐことができず、新たなウィンドウは別のフレーム内でオープンされるかもしれないが(表示するウィンドウの選択を参照)、save-window-excursionが保存およびリストアするのは、カレントフレーム上のウィンドウ構成だけだからである。

このマクロをwindow-size-change-functions内で使用してはならない。このマクロをexitすることによりwindow-size-change-functionsの実行がトリガーされるが、これは無限ループを引き起こす。

Function: window-configuration-p object: この関数は、objectがウィンドウ構成ならtをリターンする。

Function: compare-window-configurations config1 config2

This function compares two window configurations as regards the structure of windows, but ignores the values of point and the saved scrolling positions—it can return t even if those aspects differ.

The function equal can also compare two window configurations; it regards configurations as unequal if they differ in any respect, even a saved point.

Function: window-configuration-frame config: この関数は、ウィンドウ構成configが作成されたフレームをリターンする。

ウィンドウ構成の内部を調べる他のプリミティブも有用かもしれませんが、わたしたちはこれらを必要としないので実装されていません。ウィンドウ構成にたいしてより多くの操作を知りたい場合は、ファイルwinner.elを参照してください。

current-window-configurationがリターンするオブジェクトは、Emacsプロセスとともに終焉します。ウィンドウ構成をディスク上に格納して、それを別のEmacsセッションに読み戻すために、次に説明する関数を使用できます。これらの関数は、フレームの状態を任意の生きたウィンドウにクローンする場合も有用です(set-window-configurationはフレームのウィンドウを、そのフレームのルートウィンドウだけに効果的にクローンする)。

Function: window-state-get &optional window writable

この関数は、windowの状態をLispオブジェクトとしてリターンする。引数windowは有効なウィンドウでなければならず、デフォルトは選択されたフレームのルートウィンドウである。

オプション引数writableが非nilの場合、それはwindow-pointやwindow-startのようなサンプリング位置にたいするマーカーを使用しないことを意味する。この状態をディスクに書き込んで別のセッションに読み戻す場合は、この引数は非nilであること。

引数writableと変数window-persistent-parametersの両方で、この関数によりどのウィンドウパラメーターが保存されるかを指定する。ウィンドウのパラメーターを参照のこと。

window-state-getによりリターンされる値は、同一セッション内の他のウィンドウ内にあるウィンドウのクローンを作成するために使用できます。これはディスクに書き込んで、別のセッションに読み戻すこともできます。どちらの場合でも、ウィンドウの状態をリストアするためには以下の関数を使用します。

Function: window-state-put state &optional window ignore

この関数は、ウィンドウ状態stateをwindow内にputする。引数stateは以前に呼び出したwindow-state-getがリターンしたウィンドウ状態であること。オプション引数windowには生きたウィンドウ、または内部ウィンドウ(ウィンドウとフレームを参照)のいずれかを指定でき、デフォルトは選択されたウィンドウである。windowが生きていない場合は、stateをputする前に生きたウィンドウに置き換える。

オプション引数ignoreが非nilの場合、それは最小ウィンドウサイズと固定サイズの制限を無視することを意味する。ignoreがsafeなら、それは1行および/または2列まで、できる限り小さくできることを意味する。

The functions window-state-get and window-state-put also allow to exchange the contents of two live windows. The following function does precisely that:

Command: window-swap-states &optional window-1 window-2 size

This command swaps the states of the two live windows window-1 and window-2. window-1 must specify a live window and defaults to the selected one. window-2 must specify a live window and defaults to the window following window-1 in the cyclic ordering of windows, excluding minibuffer windows and including live windows on all visible frames.

Optional argument size non-nil means to try swapping the sizes of window-1 and window-2 as well. A value of height means to swap heights only, a value of width means to swap widths only, while t means to swap both widths and heights, if possible. Frames are not resized by this function.

28.29 ウィンドウのパラメーター

このセクションでは、ウィンドウに追加の情報を関連付けるためにウィンドウパラメーターを使用する方法を説明します。

Function: window-parameter window parameter: この関数は、windowのparameterの値をリターンする。windowのデフォルトは、選択されたウィンドウである。windowにparameterにたいするセッティングがない場合、この関数はnilをリターンする。

Function: window-parameters &optional window: この関数は、windowのすべてのパラメーターと、その値をリターンする。windowのデフォルトは、選択されたウィンドウである。リターン値はnil、または(parameter . value)という形式をもつ要素からなる連想リストである。

Function: set-window-parameter window parameter value: この関数は、windowのparameterの値にvalueをセットして、valueをリターンする。windowのデフォルトは、選択されたウィンドウである。

デフォルトでは、ウィンドウ構成(window configuration)やウィンドウ状態(states of windows)の保存とリストアを行う関数は、ウィンドウパラメーターについては関知しません(ウィンドウの構成を参照)。これは、save-window-excursionのbody内でパラメーターの値を変更したときは、そのマクロのexit時に以前の値がリストアされないことを意味します。これはまた、以前にwindow-state-getで保存されたウィンドウ状態をwindow-state-putでリストアしたときは、クローンされたすべてのウィンドウのパラメーターがnilにリセットされることも意味します。以下の変数により、この標準の挙動をオーバーライドできます:

Variable: window-persistent-parameters

この変数は、current-window-configurationとwindow-state-getにより保存され、set-window-configurationとwindow-state-putによりリストアされるパラメーターを指定するalistである。ウィンドウの構成を参照のこと。

このalistの各エントリーのCARはパラメーターを指定するシンボルである。CDRは以下のいずれかであること:

nil: この値は、そのパラメーターがwindow-state-getとcurrent-window-configurationのいずれによっても保存されていないことを意味する。
t: この値は、そのパラメーターがcurrent-window-configuration、および(writable引数がnilの場合は)window-state-getにより保存されたことを意味する。
writable: これは、そのパラメーターが無条件でcurrent-window-configurationとwindow-state-getの両方により保存されたことを意味する。この値は、入力構文(read syntax)をもたないパラメーターに使用するべきではない。使用した場合、別のセッションでwindow-state-putを呼び出すと、invalid-read-syntaxエラーで失敗するだろう。

Some functions (notably delete-window, delete-other-windows and split-window), may behave specially when the window specified by their window argument has a parameter whose name is equal to the function’s name. You can override such special behavior by binding the following variable to a non-nil value:

Variable: ignore-window-parameters

この変数が非nilの場合、いくつかの標準関数はウィンドウパラメーターを処理しない。現在のところ影響を受ける関数はsplit-window、delete-window、delete-other-windows、other-windowである。

アプリケーションは、これらの関数の呼び出し周辺で、この変数を非nilにバインドできる。これを行った場合、そのアプリケーションはその関数のexit時に、関連するすべてのウィンドウのパラメーターを正しく割り当てる責任をもつ。

以下のパラメーターは現在のところ、ウィンドウ管理コードにより使用されています:

delete-window

このパラメーターは、delete-windowの実行に影響する(ウィンドウの削除を参照)。

delete-other-windows

このパラメーターは、delete-other-windowsの実行に影響する(ウィンドウの削除を参照)。

no-delete-other-windows

This parameter marks the window as not deletable by delete-other-windows (see section ウィンドウの削除).

split-window

このパラメーターは、split-windowの実行に影響する(ウィンドウの分割を参照)。

other-window

このパラメーターは、other-windowの実行に影響する(ウィンドウのサイクル順を参照)。

no-other-window

このパラメーターは、そのウィンドウをother-windowにより選択不可とマークする(ウィンドウのサイクル順を参照)。

clone-of

このパラメーターは、そのウィンドウがクローンされたことを指定する。これはwindow-state-getによりインストールされる(ウィンドウの構成を参照)。

window-preserved-size

This parameter specifies a buffer, a direction where nil means vertical and t horizontal, and a size in pixels. If this window displays the specified buffer and its size in the indicated direction equals the size specified by this parameter, then Emacs will try to preserve the size of this window in the indicated direction. This parameter is installed and updated by the function window-preserve-size (see section Preserving Window Sizes).

quit-restore

このパラメーターは、バッファー表示関数によりインストールされ、quit-restore-windowにより参照される(ウィンドウのquitを参照)。これは4つの要素を含む:

The first element is one of the symbols window, meaning that the window has been specially created by display-buffer; frame, a separate frame has been created; same, the window has only ever displayed this buffer; or other, the window showed another buffer before. frame and window affect how the window is quit, while same and other affect the redisplay of buffers previously shown in this window.

The second element is either one of the symbols window or frame, or a list whose elements are the buffer shown in the window before, that buffer’s window start and window point positions, and the window’s height at that time. If that buffer is still live when the window is quit, then the function quit-restore-window reuses the window to display the buffer.

The third element is the window selected at the time the parameter was created. If quit-restore-window deletes the window passed to it as argument, it then tries to reselect this window.

4つ目の要素は、その表示がこのパラメーターの生成を引き起こしたバッファーである。quit-restore-windowは、指定されたウィンドウがまだそのバッファーを表示している場合のみ、それを削除する。

See the description of quit-restore-window in ウィンドウのquit for details.

window-side window-slot

These parameters are used for implementing side windows (see section Side Windows).

window-atom

This parameter is used for implementing atomic windows, see Atomic Windows.

mode-line-format

This parameter replaces the value of the buffer-local variable mode-line-format (see section モードラインの基礎) of this window’s buffer whenever this window is displayed. The symbol none means to suppress display of a mode line for this window. Display and contents of the mode line on other windows showing this buffer are not affected.

header-line-format

This parameter replaces the value of the buffer-local variable header-line-format (see section モードラインの基礎) of this window’s buffer whenever this window is displayed. The symbol none means to suppress display of a header line for this window. Display and contents of the header line on other windows showing this buffer are not affected.

min-margins

The value of this parameter is a cons cell whose CAR and CDR, if non-nil, specify the minimum values (in columns) for the left and right margin of this window. When present, Emacs will use these values instead of the actual margin widths for determining whether a window can be split or shrunk horizontally.

Emacs never auto-adjusts the margins of any window after splitting or resizing it. It is the sole responsibility of any application setting this parameter to adjust the margins of this window as well as those of any new window that inherits this window’s margins due to a split. Both window-configuration-change-hook and window-size-change-functions (see section ウィンドウのスクロールと変更のためのフック) should be employed for this purpose.

This parameter was introduced in Emacs version 25.1 to support applications that use large margins to center buffer text within a window and should be used, with due care, exclusively by those applications. It might be replaced by an improved solution in future versions of Emacs.

28.30 ウィンドウのスクロールと変更のためのフック

このセクションでは、あるウィンドウがそのバッファーの違う部分を表示したり、別のバッファーを表示したとき常にLispプログラムを実行可能にする方法について説明します。これを変更できる3つのアクションがあります。それはウィンドウのスクロール、ウィンドウ内でのバッファーの切り替え、ウィンドウのサイズ変更です。最初の2つのアクションはwindow-scroll-functions、最後のアクションはwindow-size-change-functionsを実行します。

Variable: window-scroll-functions

この変数は、ウィンドウのスクロールによりEmacsが再表示前に呼び出すべき関数のリストを保持する。そのウィンドウ内に異なるバッファーを表示したときも、これらの関数が実行される。

This variable is not a normal hook, because each function is called with two arguments: the window, and its new display-start position. At the time of the call, the display-start position of the window argument is already set to its new value, and the buffer to be displayed in the window is already set as the current buffer.

これらの関数は、window-end(ウィンドウの開始位置と終了位置を参照)を使用する際には気をつけなければならない。最新の値が必要な場合は、それを確実に入力するためにupdate引数を使用しなければならない。

警告: ウィンドウのスクロール方法を変更するためにこの機能を使用してはならない。これは、そのような用途のためにデザインされておらず、そのような使用は機能しないだろう。

Function: run-window-scroll-functions &optional window: This function calls window-scroll-functions for the specified window, which defaults to the selected window.

Variable: window-size-change-functions

This variable holds a list of functions to be called if the size of any window changes for any reason. The functions are called once per redisplay, and once for each frame on which size changes have occurred.

Each function receives the frame as its sole argument. To find out whether a specific window has changed size, compare the return values of window-pixel-width-before-size-change and window-pixel-width respectively window-pixel-height-before-size-change and window-pixel-height for that window (see section ウィンドウのサイズ).

These function are usually only called when at least one window was added or has changed size since the last time this hook was run for the associated frame. In some rare cases this hook also runs when a window that was added intermittently has been deleted afterwards. In these cases none of the windows on the frame will appear to have changed its size.

You may use save-selected-window in these functions (see section ウィンドウの選択). However, do not use save-window-excursion (see section ウィンドウの構成); exiting that macro counts as a size change, which would cause these functions to be called again.

Variable: window-configuration-change-hook

A normal hook that is run every time the window configuration of a frame changes. Window configuration changes include splitting and deleting windows, and the display of a different buffer in a window. Resizing the frame or individual windows do not count as configuration changes. Use window-size-change-functions, see above, when you want to track size changes that are not caused by the deletion or creation of windows.

The buffer-local value of this hook is run once for each window on the affected frame, with the relevant window selected and its buffer current. The global value of this hook is run once for the modified frame, with that frame selected.

Function: run-window-configuration-change-hook &optional frame: This function runs window-configuration-change-hook for the specified frame, which defaults to the selected frame.

加えて、Font Lockフォント表示関数(Font Lock fontification function)を登録するために、jit-lock-registerを使用できる。バッファーの一部が(再)フォント表示されたときは、ウィンドウがスクロール、またはサイズ変更されたという理由で、これが常に呼び出されるだろう。Font Lockのその他の変数を参照のこと。

29 フレーム

フレーム(frame)とは、1つ以上のEmacsウィンドウを含むスクリーンオブジェクトです(ウィンドウを参照)。これは、グラフィカル環境では“ウィンドウ”と呼ばれる類のオブジェクトです。しかし、Emacsはこの単語を異なる方法で使用しているので、ここではそれを“ウィンドウ”と呼ぶことはできません。Emacs Lispにおいてフレームオブジェクト(frame object)とは、スクリーン上のフレームを表すLispオブジェクトです。フレーム型を参照してください。

フレームには最初、1つのメインウィンドウおよび/またはミニバッファーウィンドウが含まれます。メインウィンドウは、より小さいウィンドウに垂直、または水平に分割することができます。ウィンドウの分割を参照してください。

端末(terminal)とは、1つ以上のEmacsフレームを表示する能力のあるデバイスのことです。Emacs Lispにおいて、端末オブジェクト(terminal object)とは端末を表すLispオブジェクトです。端末型を参照してください。

端末にはテキスト端末(text terminals)とグラフィカル端末(graphical terminals)という、2つのクラスがあります。テキスト端末はグラフィック能力をもたないディスプレイで、xtermやその他の端末エミュレーターが含まれます。テキスト端末上では、それぞれのEmacsフレームは、その端末のスクリーン全体を占有します。たとえ追加のフレームを作成してそれらを切り替えることができたとしても、端末が表示するのは一度に1つのフレームだけです。一方でグラフィカル端末は、X Window Systemのようなグラフィカルディスプレイシステムにより管理されています。これにより、Emacsは同一ディスプレイ上に複数のフレームを同時に表示することができます。

GNUおよびUnix systemsシステムでは、単一のEmacsセッション内で、そのEmacsがテキスト端末とグラフィカル端末のいずれで開始されたかに関わらず、任意の利用可能な端末上で、追加のフレームを作成することができます。Emacsは、グラフィカル端末とテキスト端末の両方を、同時に表示することができます。これはたとえば、リモート地から同じセッションに接続する際などに便利でしょう。複数の端末を参照してください。

Function: framep object

この述語(predicate)は、objectがフレームなら非nil、それ以外はnilをリターンする。フレームにたいしては、フレームが使用するディスプレイの種類の値となる:

t: そのフレームはテキスト端末上で表示されている。
x: そのフレームはXグラフィカル端末上で表示されている。
w32: そのフレームはMS-Windowsグラフィカル端末上で表示されている。
ns: そのフレームはGNUStepまたはMacintosh Cocoaグラフィカル端末上で表示されている。
pc: そのフレームはMS-DOS端末上で表示されている。

Function: frame-terminal &optional frame: この関数は、frameを表示する端末オブジェクトをリターンする。frameがnilまたは未指定の場合のデフォルトは、選択されたフレームである。

Function: terminal-live-p object: この述語は、objectが生きた(削除されていない)端末なら非nil、それ以外はnilをリターンする。生きた端末にたいしては、リターン値はその端末上で表示されているフレームの種類を示す。可能な値は、上述のframepと同様。

On a graphical terminal we distinguish two types of frames: A normal top-level frame is a frame whose window-system window is a child of the window-system’s root window for that terminal. A child frame is a frame whose window-system window is the child of the window-system window of another Emacs frame. See section Child Frames.

29.1 フレームの作成		追加のフレームの作成。
29.2 複数の端末		異なる複数デバイス上での表示。
29.3 Frame Geometry		Geometric properties of frames.
29.4 フレームのパラメーター		フレームのサイズ、位置、フォント等の制御。
29.5 端末のパラメーター		端末上のすべてのフレームにたいして一般的なパラメーター。
29.6 フレームのタイトル		フレームタイトルの自動的な更新。
29.7 フレームの削除		明示的に削除されるまでフレームは存続する。
29.8 すべてのフレームを探す		すべての既存フレームを調べる方法。
29.9 ミニバッファーとフレーム		フレームが使用するミニバッファーを見つける方法。
29.10 入力のフォーカス		選択されたフレームの指定。
29.11 フレームの可視性		フレームは可視、不可視、またはアイコン化されているかもしれない。
29.12 Raising, Lowering and Restacking Frames
29.13 フレーム構成		すべてのフレームの状態の保存。
29.14 Child Frames		Making a frame the child of another.
29.15 マウスの追跡		マウス移動時のイベントの取得。
29.16 マウスの位置		マウスの場所や移動を問い合わせる。
29.17 ポップアップメニュー		ユーザーに選択させるためのメニューの表示。
29.18 ダイアログボックス		yes/noを問い合わせるためのボックスの表示。
29.19 ポインターの形状		マウスポインターのシェイプの指定。
29.20 ウィンドウシステムによる選択		他のXクライアントとのテキストの転送。
29.21 ドラッグアンドドロップ		ドラッグアンドドロップの実装の内部。
29.22 カラー名		カラー名定義の取得。
29.23 テキスト端末のカラー		テキスト端末のカラーの定義。
29.24 Xリソース		サーバーからのリソース値の取得。
29.25 ディスプレー機能のテスト		端末の機能の判定。

29.1 フレームの作成

新たにフレームを作成するためには、関数make-frameを呼び出します。

Command: make-frame &optional parameters

この関数は、カレントバッファーを表示するフレームを作成して、それをリターンする。

The parameters argument is an alist that specifies frame parameters for the new frame. See section フレームのパラメーター. If you specify the terminal parameter in parameters, the new frame is created on that terminal. Otherwise, if you specify the window-system frame parameter in parameters, that determines whether the frame should be displayed on a text terminal or a graphical terminal. See section ウィンドウシステム. If neither is specified, the new frame is created in the same terminal as the selected frame.

Any parameters not mentioned in parameters default to the values in the alist default-frame-alist (see section フレームの初期パラメーター); parameters not specified there default from the X resources or its equivalent on your operating system (see X Resources in The GNU Emacs Manual). After the frame is created, this function applies any parameters specified in frame-inherited-parameters (see below) it has no assigned yet, taking the values from the frame that was selected when make-frame was called.

Note that on multi-monitor displays (see section 複数の端末), the window manager might position the frame differently than specified by the positional parameters in parameters (see section 位置のパラメーター). For example, some window managers have a policy of displaying the frame on the monitor that contains the largest part of the window (a.k.a. the dominating monitor).

この関数自体はーが、新たなフレームを選択されたフレームにする訳ではない。See section 入力のフォーカスを参照のこと。以前に選択されていたフレームは、選択されたままである。しかしグラフィカル端末上では、ウィンドウシステム自身の理由により、新たなフレームが選択されるかもしれない。

Variable: before-make-frame-hook: make-frameがフレームを作成する前に、それにより実行されるノーマルフック。

Variable: after-make-frame-functions: An abnormal hook run by make-frame after it created the frame. Each function in after-make-frame-functions receives one argument, the frame just created.

Note that any functions added to these hooks by your initial file are usually not run for the initial frame, since Emacs reads the initial file only after creating that frame. However, if the initial frame is specified to use a separate minibuffer frame (see section ミニバッファーとフレーム), the functions will be run for both, the minibuffer-less and the minibuffer frame.

Variable: frame-inherited-parameters: This variable specifies the list of frame parameters that a newly created frame inherits from the currently selected frame. For each parameter (a symbol) that is an element in this list and has not been assigned earlier when processing make-frame, the function sets the value of that parameter in the created frame to its value in the selected frame.

29.2 複数の端末

Emacsは、それぞれの端末を端末オブジェクト(terminal object)というデータ型で表します(端末型を参照)。GNUおよびUnixシステムでは、Emacsはそれぞれのセッション内で複数の端末を同時に実行できます。その他のシステムでは、単一の端末だけが使用できます。端末オブジェクトはそれぞれ、以下の属性をもちます:

その端末により使用されるデバイスの名前(たとえば‘:0.0’や/dev/tty)。
その端末により使用される端末とキーボードのコーディングシステム。端末I/Oのエンコーディングを参照のこと。
その端末に関連付けられたディスプレイの種類。これは、関数terminal-live-pによりリターンされるシンボル(たとえばx、t、w32、ns、pc)である。フレームを参照のこと。
端末パラメーターのリスト。端末のパラメーターを参照のこと。

端末オブジェクトを作成するプリミティブはありません。make-frame-on-display(以下参照)を呼び出したときなど、Emacsは必要に応じてそれらを作成します。

Function: terminal-name &optional terminal: この関数は、terminalにより使用されるデバイスのファイル名をリターンする。terminalが省略またはnilの場合のデフォルトは、選択されたフレームの端末である。terminalはフレームでもよく、その場合はそのフレームの端末となる。

Function: terminal-list: この関数は、すべての生きた端末オブジェクトのリストをリターンする。

Function: get-device-terminal device: この関数は、deviceにより与えられたデバイス名の端末をリターンする。deviceが文字列の場合は端末デバイス名、または‘host:server.screen’という形式のXディスプレイ名のいずれかを指定できる。deviceの場合、この関数はそのフレームの端末をリターンする。nilは選択されたフレームを意味する。最後に、もしdeviceが生きた端末を表す端末オブジェクトなら、その端末がリターンされる。引数がこれらのいずれとも異なる場合、この関数はエラーをシグナルする。

Function: delete-terminal &optional terminal force

この関数は、terminal上のすべてのフレームを削除して、それらが使用していたリソースを解放する。これらはアブノーマルフックdelete-terminal-functionsを実行し、各関数の引数としてterminalを渡す。

terminalが省略またはnilの場合のデフォルトは、選択されたフレームの端末である。terminalはフレームでもよく、その場合はそのフレームの端末を意味する。

この関数は通常、唯一アクティブな端末の削除を試みるとエラーをシグナルするが、forceが非nilなら、これを行うことができる。端末上で最後のフレームを削除した際、Emacsは自動的にこの関数を呼び出す(フレームの削除を参照)。

Variable: delete-terminal-functions: delete-terminalにより実行されるアブノーマルフック。各関数は、delete-terminalに渡されたterminalを、唯一の引数として受け取る。技術的な詳細により、この関数は端末の削除の直前、または直後のいずれかに呼び出される。

数は多くありませんが、いくつかのLisp変数は端末ローカル(terminal-local)です。つまり、それらは端末それぞれにたいして、個別にバインディングをもちます。いかなるときも、実際に効果をもつバインディングは、カレントで選択されたフレームに属する端末にたいして1つだけです。これらの変数にはdefault-minibuffer-frame、defining-kbd-macro、last-kbd-macro、system-key-alistが含まれます。これらは常に端末ローカルであり、決してバッファーローカル(バッファーローカル変数を参照)にはできません。

On GNU and Unix systems, each X display is a separate graphical terminal. When Emacs is started from within the X window system, it uses the X display specified by the DISPLAY environment variable, or by the ‘--display’ option (see Initial Options in The GNU Emacs Manual). Emacs can connect to other X displays via the command make-frame-on-display. Each X display has its own selected frame and its own minibuffer windows; however, only one of those frames is the selected frame at any given moment (see section 入力のフォーカス). Emacs can even connect to other text terminals, by interacting with the emacsclient program. See Emacs Server in The GNU Emacs Manual.

1つのXサーバーが、1つ以上のディスプレイを処理できます。各Xディスプレイには、‘hostname:displaynumber.screennumber’という3つの部分からなる名前があります。1つ目の部分のhostnameは、その端末が物理的に接続されるマシン名です。2つ目の部分のdisplaynumberは、同じキーボードとポインティングデバイス(マウスやタブレット等)を共有するマシンに接続された、1つ以上のモニターを識別するための、0基準の番号です。3つ目の部分のscreennumberは、そのXサーバー上の単一のモニターコレクション(a single monitor collection)の一部である、0基準のスクリーン番号(個別のモニター)です。1つのサーバー配下にある2つ以上のスクリーンを使用する際、Emacsはそれらの名前の同一部分から、それらが単一のキーボードを共有することを知ることができるのです。

MS-WindowsのようにXウィンドウシステムを使用しないシステムは、Xディスプレイの概念をサポートせず、各ホスト上には1つのディスプレイだけがあります。これらのシステム上のディスプレイ名は、上述したような3つの部分からなる名前にしたがいません。たとえば、MS-Windowsシステム上のディスプレイ名は文字列定数‘w32’です。これは互換性のために存在するものであり、ディスプレイ名を期待する関数にこれを渡すことができます。

Command: make-frame-on-display display &optional parameters

この関数は、display上に新たにフレームを作成して、それをリターンする。その他のフレームパラメーターは、alist parametersから取得する。displayはXディスプレイの名前(文字列)であること。

Before creating the frame, this function ensures that Emacs is set up to display graphics. For instance, if Emacs has not processed X resources (e.g., if it was started on a text terminal), it does so at this time. In all other respects, this function behaves like make-frame (see section フレームの作成).

Function: x-display-list: この関数は、EmacsがどのXディスプレイに接続したかを識別するリストをリターンする。このリストの要素は文字列で、それぞれがディスプレイ名を表す。

Function: x-open-connection display &optional xrm-string must-succeed

この関数は、ディスプレイ上にフレームを作成することなく、Xディスプレイdisplayへの接続をオープンする。通常は、make-frame-on-displayが自動的に呼び出すので、Emacs Lispプログラムがこの関数を呼び出す必要はない。これを呼び出す唯一の理由は、与えられたXディスプレイにたいして通信を確立できるかどうかチェックするためである。

オプション引数xrm-stringが非nilなら、それは.Xresourcesファイル内で使用されるフォーマットと同一な、リソース名とリソース値である。X Resources in The GNU Emacs Manualを参照のこと。これらの値はそのXサーバー上で記録されたリソース値をオーバーライドして、このディスプレイ上で作成されるすべてのEmacsフレームにたいして適用される。以下は、この文字列がどのようなものかを示す例である:

"*BorderWidth: 3\n*InternalBorder: 2\n"

must-succeedが非nilなら、接続オープンの失敗によりEmacsが終了させられる。それ以外の場合は、通常のLispエラーとなる。

Function: x-close-connection display: この関数は、ディスプレイdisplayへの接続をクローズする。これを行う前にまず、そのディスプレイ上でオープンしたすべてのフレームを削除しなければならない(フレームの削除を参照)。

On some multi-monitor setups, a single X display outputs to more than one physical monitor. You can use the functions display-monitor-attributes-list and frame-monitor-attributes to obtain information about such setups.

Function: display-monitor-attributes-list &optional display

この関数は、display上の物理モニターの属性のリストをリターンする。displayにはディスプレイ名(文字列)、端末、フレームを指定でき、省略またはnilの場合のデフォルトは、選択されたフレームのディスプレイである。このリストの各要素は、物理モニターの属性を表す連想リストである。1つ目の要素はプライマリーモニターである。以下は属性のキーと値である:

‘geometry’: ‘(x y width height)’のような、ピクセル単位でのそのモニターのスクリーンの左上隅の位置、そのサイズ。そのモニターがプライマリーモニターでない場合は、いくつかの座標が負になり得る。
‘workarea’: Position of the top-left corner and size of the work area (usable space) in pixels as ‘(x y width height)’. This may be different from ‘geometry’ in that space occupied by various window manager features (docks, taskbars, etc.) may be excluded from the work area. Whether or not such features actually subtract from the work area depends on the platform and environment. Again, if the monitor is not the primary monitor, some of the coordinates might be negative.
‘mm-size’: ‘(width height)’<のような、ミリメートル単位での幅と高さ。
‘frames’: その物理モニターが支配(dominate)するフレームのリスト(以下参照)。
‘name’: stringのような、その物理モニターの名前。
‘source’: stringのような、マルチモニターの情報ソース(例: ‘XRandr’、‘Xinerama’等)。

x、y、width、heightは整数。‘name’と‘source’は欠落しているかもしれない。

あるモニター内にフレームの最大領域がある、または(フレームがどの物理モニターに跨がらないなら)そのモニターがフレームに最も近いとき、フレームは物理モニターにより支配(dominate)される。グラフィカルなディスプレイ内の(ツールチップではない)すべてのフレームは、たとえそのフレームが複数の物理モニターに跨がる(または物理モニター上にない)としても、(可視か否かによらず)正確に1つの物理モニターにより支配される。

以下は、2つのモニターディスプレイ上でこの関数により生成されたデータの例である:

  (display-monitor-attributes-list)
  ⇒
  (((geometry 0 0 1920 1080) ;; 左手側プライマリーモニター
    (workarea 0 0 1920 1050) ;; タスクバーが幾分かの高さを占有
    (mm-size 677 381)
    (name . "DISPLAY1")
    (frames #<frame emacs@host *Messages* 0x11578c0>
            #<frame emacs@host *scratch* 0x114b838>))
   ((geometry 1920 0 1680 1050) ;; 右手側モニター
    (workarea 1920 0 1680 1050) ;; スクリーン全体を使用可
    (mm-size 593 370)
    (name . "DISPLAY2")
    (frames)))

Function: frame-monitor-attributes &optional frame: この関数は、 frameを支配(上記参照)する物理モニターの属性をリターンする。 frameのデフォルトは選択されたフレームである。

29.3 Frame Geometry

The geometry of a frame depends on the toolkit that was used to build this instance of Emacs and the terminal that displays the frame. This chapter describes these dependencies and some of the functions to deal with them. Note that the frame argument of all of these functions has to specify a live frame (see section フレームの削除). If omitted or nil, it specifies the selected frame (see section 入力のフォーカス).

29.3.1 Frame Layout

A visible frame occupies a rectangular area on its terminal’s display. This area may contain a number of nested rectangles, each serving a different purpose. The drawing below sketches the layout of a frame on a graphical terminal:


        <------------ Outer Frame Width ----------->
        ____________________________________________
     ^(0)  ________ External/Outer Border _______   |
     | |  |_____________ Title Bar ______________|  |
     | | (1)_____________ Menu Bar ______________|  | ^
     | | (2)_____________ Tool Bar ______________|  | ^
     | | (3) _________ Internal Border ________  |  | ^
     | |  | |   ^                              | |  | |
     | |  | |   |                              | |  | |
Outer  |  | | Inner                            | |  | Native
Frame  |  | | Frame                            | |  | Frame
Height |  | | Height                           | |  | Height
     | |  | |   |                              | |  | |
     | |  | |<--+--- Inner Frame Width ------->| |  | |
     | |  | |   |                              | |  | |
     | |  | |___v______________________________| |  | |
     | |  |___________ Internal Border __________|  | v
     v |___________ External/Outer Border __________|
           <-------- Native Frame Width -------->

In practice not all of the areas shown in the drawing will or may be present. The meaning of these areas is described below.

‘Outer Frame’

The outer frame is a rectangle comprising all areas shown in the drawing. The edges of that rectangle are called the outer edges of the frame. Together, the outer width and outer height of the frame specify the outer size of that rectangle.

Knowing the outer size of a frame is useful for fitting a frame into the working area of its display (see section 複数の端末) or for placing two frames adjacent to each other on the screen. Usually, the outer size of a frame is available only after the frame has been mapped (made visible, see section フレームの可視性) at least once. For the initial frame or a frame that has not been created yet, the outer size can be only estimated or must be calculated from the window-system’s or window manager’s defaults. One workaround is to obtain the differences of the outer and native (see below) sizes of a mapped frame and use them for calculating the outer size of the new frame.

The position of the upper left corner of the outer frame (indicated by ‘(0)’ in the drawing above) is the outer position of the frame. The outer position of a graphical frame is also referred to as “the position” of the frame because it usually remains unchanged on its display whenever the frame is resized or its layout is changed.

The outer position is specified by and can be set via the left and top frame parameters (see section 位置のパラメーター). For a normal, top-level frame these parameters usually represent its absolute position (see below) with respect to its display’s origin. For a child frame (see section Child Frames) these parameters represent its position relative to the native position (see below) of its parent frame. For frames on text terminals the values of these parameters are meaningless and always zero.

‘External Border’

The external border is part of the decorations supplied by the window manager. It is typically used for resizing the frame with the mouse and is therefore not shown on “fullboth” and maximized frames (see section サイズのパラメーター). Its width is determined by the window manager and cannot be changed by Emacs’ functions.

External borders don’t exist on text terminal frames. For graphical frames, their display can be suppressed by setting the override-redirect or undecorated frame parameter (see section ウィンドウ管理のパラメーター).

‘Outer Border’

The outer border is a separate border whose width can be specified with the border-width frame parameter (see section レイアウトのパラメーター). In practice, either the external or the outer border of a frame are displayed but never both at the same time. Usually, the outer border is shown only for special frames that are not (fully) controlled by the window manager like tooltip frames (see section Tooltips), child frames (see section Child Frames) and undecorated or override-redirect frames (see section ウィンドウ管理のパラメーター).

Outer borders are never shown on text terminal frames and on frames generated by GTK+ routines. On MS-Windows, the outer border is emulated with the help of a one pixel wide external border. Non-toolkit builds on X allow to change the color of the outer border by setting the border-color frame parameter (see section レイアウトのパラメーター).

‘Title Bar’

The title bar, a.k.a. caption bar, is also part of the window manager’s decorations and typically displays the title of the frame (see section フレームのタイトル) as well as buttons for minimizing, maximizing and deleting the frame. It can be also used for dragging the frame with the mouse. The title bar is usually not displayed for fullboth (see section サイズのパラメーター), tooltip (see section Tooltips) and child frames (see section Child Frames) and doesn’t exist for terminal frames. Display of the title bar can be suppressed by setting the override-redirect or the undecorated frame parameters (see section ウィンドウ管理のパラメーター).

‘Menu Bar’

The menu bar (see section メニューバー Bar) can be either internal (drawn by Emacs itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid, Motif and MS-Windows) rely on an external menu bar. NS also uses an external menu bar which, however, is not part of the outer frame. Non-toolkit builds can provide an internal menu bar. On text terminal frames, the menu bar is part of the frame’s root window (see section ウィンドウとフレーム). As a rule, menu bars are never shown on child frames (see section Child Frames). Display of the menu bar can be suppressed by setting the menu-bar-lines parameter (see section レイアウトのパラメーター) to zero.

Whether the menu bar is wrapped or truncated whenever its width becomes too large to fit on its frame depends on the toolkit . Usually, only Motif and MS-Windows builds can wrap the menu bar. When they (un-)wrap the menu bar, they try to keep the outer height of the frame unchanged, so the native height of the frame (see below) will change instead.

‘Tool Bar’

Like the menu bar, the tool bar (see section ツールバー) can be either internal (drawn by Emacs itself) or external (drawn by a toolkit). The GTK+ and NS builds have the tool bar drawn by the toolkit. The remaining builds use internal tool bars. With GTK+ the tool bar can be located on either side of the frame, immediately outside the internal border, see below. Tool bars are usually not shown for child frames (see section Child Frames). Display of the tool bar can be suppressed by setting the tool-bar-lines parameter (see section レイアウトのパラメーター) to zero.

If the variable auto-resize-tool-bars is non-nil, Emacs wraps the internal tool bar when its width becomes too large for its frame. If and when Emacs (un-)wraps the internal tool bar, it by default keeps the outer height of the frame unchanged, so the native height of the frame (see below) will change instead. Emacs built with GTK+, on the other hand, never wraps the tool bar but may automatically increase the outer width of a frame in order to accommodate an overlong tool bar.

‘Native Frame’

The native frame is a rectangle located entirely within the outer frame. It excludes the areas occupied by an external or outer border, the title bar and any external menu or tool bar. The edges of the native frame are called the native edges of the frame. Together, the native width and native height of a frame specify the native size of the frame.

The native size of a frame is the size Emacs passes to the window-system or window manager when creating or resizing the frame from within Emacs. It is also the size Emacs receives from the window-system or window manager whenever these resize the frame’s window-system window, for example, after maximizing the frame by clicking on the corresponding button in the title bar or when dragging its external border with the mouse.

The position of the top left corner of the native frame specifies the native position of the frame. (1)–(3) in the drawing above indicate that position for the various builds:

(1) non-toolkit and terminal frames
(2) Lucid, Motif and MS-Windows frames
(3) GTK+ and NS frames

Accordingly, the native height of a frame may include the height of the tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or those of the menu bar and the tool bar (non-toolkit and text terminal frames).

The native position of a frame is the reference position for functions that set or return the current position of the mouse (see section マウスの位置) and for functions dealing with the position of windows like window-edges, window-at or coordinates-in-window-p (see section 座標とウィンドウ). It also specifies the (0, 0) origin for locating and positioning child frames within this frame (see section Child Frames).

Note also that the native position of a frame usually remains unaltered on its display when removing or adding the window manager decorations by changing the frame’s override-redirect or undecorated parameter (see section ウィンドウ管理のパラメーター).

‘Internal Border’

The internal border is a border drawn by Emacs around the inner frame (see below). Its width is specified by the internal-border-width frame parameter (see section レイアウトのパラメーター). Its color is specified by the background of the internal-border face.

‘Inner Frame’

The inner frame is the rectangle reserved for the frame’s windows. It’s enclosed by the internal border which, however, is not part of the inner frame. Its edges are called the inner edges of the frame. The inner width and inner height specify the inner size of the rectangle. The inner frame is sometimes also referred to as the display area of the frame.

As a rule, the inner frame is subdivided into the frame’s root window (see section ウィンドウとフレーム) and the frame’s minibuffer window (see section ミニバッファーのウィンドウ). There are two notable exceptions to this rule: A minibuffer-less frame contains a root window only and does not contain a minibuffer window. A minibuffer-only frame contains only a minibuffer window which also serves as that frame’s root window. See フレームの初期パラメーター for how to create such frame configurations.

‘Text Area’

The text area of a frame is a somewhat fictitious area that can be embedded in the native frame. Its position is unspecified. Its width can be obtained by removing from that of the native width the widths of the internal border, one vertical scroll bar, and one left and one right fringe if they are specified for this frame, see レイアウトのパラメーター. Its height can be obtained by removing from that of the native height the widths of the internal border and the heights of the frame’s internal menu and tool bars and one horizontal scroll bar if specified for this frame.

The absolute position of a frame is given as a pair (X, Y) of horizontal and vertical pixel offsets relative to an origin (0, 0) of the frame’s display. Correspondingly, the absolute edges of a frame are given as pixel offsets from that origin.

Note that with multiple monitors, the origin of the display does not necessarily coincide with the top-left corner of the entire usable display area of the terminal. Hence the absolute position of a frame can be negative in such an environment even when that frame is completely visible.

By convention, vertical offsets increase “downwards”. This means that the height of a frame is obtained by subtracting the offset of its top edge from that of its bottom edge. Horizontal offsets increase “rightwards”, as expected, so a frame’s width is calculated by subtracting the offset of its left edge from that of its right edge.

For a frame on a graphical terminal the following function returns the sizes of the areas described above:

Function: frame-geometry &optional frame

This function returns geometric attributes of frame. The return value is an association list of the attributes listed below. All coordinate, height and width values are integers counting pixels. Note that if frame has not been mapped yet, (see section フレームの可視性) some of the return values may only represent approximations of the actual values—those that can be seen after the frame has been mapped.

outer-position: A cons representing the absolute position of the outer frame, relative to the origin at position (0, 0) of frame’s display.
outer-size: A cons of the outer width and height of frame.
external-border-size: A cons of the horizontal and vertical width of frame’s external borders as supplied by the window manager. If the window manager doesn’t supply these values, Emacs will try to guess them from the coordinates of the outer and inner frame.
outer-border-width: The width of the outer border of frame. The value is meaningful for non-GTK+ X builds only.
title-bar-size: A cons of the width and height of the title bar of frame as supplied by the window manager or operating system. If both of them are zero, the frame has no title bar. If only the width is zero, Emacs was not able to retrieve the width information.
menu-bar-external: If non-nil, this means the menu bar is external (not part of the native frame of frame).
menu-bar-size: A cons of the width and height of the menu bar of frame.
tool-bar-external: If non-nil, this means the tool bar is external (not part of the native frame of frame).
tool-bar-position: This tells on which side the tool bar on frame is and can be one of left, top, right or bottom. The only toolkit that currently supports a value other than top is GTK+.
tool-bar-size: A cons of the width and height of the tool bar of frame.
internal-border-width: The width of the internal border of frame.

The following function can be used to retrieve the edges of the outer, native and inner frame.

Function: frame-edges &optional frame type

This function returns the absolute edges of the outer, native or inner frame of frame. frame must be a live frame and defaults to the selected one. The returned list has the form (left top right bottom) where all values are in pixels relative to the origin of frame’s display. For terminal frames the values returned for left and top are always zero.

Optional argument type specifies the type of the edges to return: outer-edges means to return the outer edges of frame, native-edges (or nil) means to return its native edges and inner-edges means to return its inner edges.

By convention, the pixels of the display at the values returned for left and top are considered to be inside (part of) frame. Hence, if left and top are both zero, the pixel at the display’s origin is part of frame. The pixels at bottom and right, on the other hand, are considered to lie immediately outside frame. This means that if you have, for example, two side-by-side frames positioned such that the right outer edge of the frame on the left equals the left outer edge of the frame on the right, the pixels at that edge show a part of the frame on the right.

29.3.2 Frame Font

Each frame has a default font which specifies the default character size for that frame. This size is meant when retrieving or changing the size of a frame in terms of columns or lines (see section サイズのパラメーター). It is also used when resizing (see section ウィンドウのサイズ) or splitting (see section ウィンドウの分割) windows.

The terms line height and canonical character height are sometimes used instead of “default character height”. Similarly, the terms column width and canonical character width are used instead of “default character width”.

Function: frame-char-height &optional frame
Function: frame-char-width &optional frame: These functions return the default height and width of a character in frame, measured in pixels. Together, these values establish the size of the default font on frame. The values depend on the choice of font for frame, see フォントとカラーのパラメーター.

The default font can be also set directly with the following function:

Command: set-frame-font font &optional keep-size frames

This sets the default font to font. When called interactively, it prompts for the name of a font, and uses that font on the selected frame. When called from Lisp, font should be a font name (a string), a font object, font entity, or a font spec.

If the optional argument keep-size is nil, this keeps the number of frame lines and columns fixed. (If non-nil, the option frame-inhibit-implied-resize described in the next section will override this.) If keep-size is non-nil (or with a prefix argument), it tries to keep the size of the display area of the current frame fixed by adjusting the number of lines and columns.

If the optional argument frames is nil, this applies the font to the selected frame only. If frames is non-nil, it should be a list of frames to act upon, or t meaning all existing and all future graphical frames.

29.3.3 Frame Position

On graphical systems, the position of a normal top-level frame is specified as the absolute position of its outer frame (see section Frame Geometry). The position of a child frame (see section Child Frames) is specified via pixel offsets of its outer edges relative to the native position of its parent frame.

You can access or change the position of a frame using the frame parameters left and top (see section 位置のパラメーター). Here are two additional functions for working with the positions of an existing, visible frame. For both functions, the argument frame must denote a live frame and defaults to the selected frame.

Function: frame-position &optional frame

For a normal, non-child frame this function returns a cons of the pixel coordinates of its outer position (see section Frame Layout) with respect to the origin (0, 0) of its display. For a child frame (see section Child Frames) this function returns the pixel coordinates of its outer position with respect to an origin (0, 0) at the native position of frame’s parent.

Negative values never indicate an offset from the right or bottom edge of frame’s display or parent frame. Rather, they mean that frame’s outer position is on the left and/or above the origin of its display or the native position of its parent frame. This usually means that frame is only partially visible (or completely invisible). However, on systems where the display’s origin does not coincide with its top-left corner, the frame may be visible on a secondary monitor.

On a text terminal frame both values are zero.

Function: set-frame-position frame x y

This function sets the outer frame position of frame to (x, y). The latter arguments specify pixels and normally count from the origin at the position (0, 0) of frame’s display. For child frames, they count from the native position of frame’s parent frame.

Negative parameter values position the right edge of the outer frame by -x pixels left from the right edge of the screen (or the parent frame’s native rectangle) and the bottom edge by -y pixels up from the bottom edge of the screen (or the parent frame’s native rectangle).

Note that negative values do not permit to align the right or bottom edge of frame exactly at the right or bottom edge of its display or parent frame. Neither do they allow to specify a position that does not lie within the edges of the display or parent frame. The frame parameters left and top (see section 位置のパラメーター) allow to do that, but may still fail to provide good results for the initial or a new frame.

This function has no effect on text terminal frames.

Variable: move-frame-functions: This hook specifies the functions that are run when an Emacs frame is moved (assigned a new position) by the window-system or window manager. The functions are run with one argument, the frame that moved. For a child frame (see section Child Frames), the functions are run only when the position of the frame changes in relation to that of its parent frame.

29.3.4 Frame Size

The canonical way to specify the size of a frame from within Emacs is by specifying its text size—a tuple of the width and height of the frame’s text area (see section Frame Layout). It can be measured either in pixels or in terms of the frame’s canonical character size (see section Frame Font).

For frames with an internal menu or tool bar, the frame’s native height cannot be told exactly before the frame has been actually drawn. This means that in general you cannot use the native size to specify the initial size of a frame. As soon as you know the native size of a visible frame, you can calculate its outer size (see section Frame Layout) by adding in the remaining components from the return value of frame-geometry. For invisible frames or for frames that have yet to be created, however, the outer size can only be estimated. This also means that calculating an exact initial position of a frame specified via offsets from the right or bottom edge of the screen (see section Frame Position) is impossible.

The text size of any frame can be set and retrieved with the help of the height and width frame parameters (see section サイズのパラメーター). The text size of the initial frame can be also set with the help of an X-style geometry specification. See Command Line Arguments for Emacs Invocation in The GNU Emacs Manual. Below we list some functions to access and set the size of an existing, visible frame, by default the selected one.

Function: frame-height &optional frame

Function: frame-width &optional frame

These functions return the height and width of the text area of frame, measured in units of the default font height and width of frame (see section Frame Font). These functions are plain shorthands for writing (frame-parameter frame 'height) and (frame-parameter frame 'width).

If the text area of frame measured in pixels is not a multiple of its default font size, the values returned by these functions are rounded down to the number of characters of the default font that fully fit into the text area.

The functions following next return the pixel widths and heights of the native, outer and inner frame and the text area (see section Frame Layout) of a given frame. For a text terminal, the results are in characters rather than pixels.

Function: frame-outer-width &optional frame
Function: frame-outer-height &optional frame: These functions return the outer width and height of frame in pixels.

Function: frame-native-height &optional frame
Function: frame-native-width &optional frame: These functions return the native width and height of frame in pixels.

Function: frame-inner-width &optional frame
Function: frame-inner-height &optional frame: These functions return the inner width and height of frame in pixels.

Function: frame-text-width &optional frame
Function: frame-text-height &optional frame: These functions return the width and height of the text area of frame in pixels.

On window systems that support it, Emacs tries by default to make the text size of a frame measured in pixels a multiple of the frame’s character size. This, however, usually means that a frame can be resized only in character size increments when dragging its external borders. It also may break attempts to truly maximize the frame or making it “fullheight” or “fullwidth” (see section サイズのパラメーター) leaving some empty space below and/or on the right of the frame. The following option may help in that case.

User Option: frame-resize-pixelwise

If this option is nil (the default), a frame’s text pixel size is usually rounded to a multiple of the current values of that frame’s frame-char-height and frame-char-width whenever the frame is resized. If this is non-nil, no rounding occurs, hence frame sizes can increase/decrease by one pixel.

Setting this variable usually causes the next resize operation to pass the corresponding size hints to the window manager. This means that this variable should be set only in a user’s initial file; applications should never bind it temporarily.

The precise meaning of a value of nil for this option depends on the toolkit used. Dragging the external border with the mouse is done character-wise provided the window manager is willing to process the corresponding size hints. Calling set-frame-size (see below) with arguments that do not specify the frame size as an integer multiple of its character size, however, may: be ignored, cause a rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows).

With some window managers you may have to set this to non-nil in order to make a frame appear truly maximized or full-screen.

Function: set-frame-size frame width height &optional pixelwise

This function sets the size of the text area of frame, measured in terms of the canonical height and width of a character on frame (see section Frame Font).

The optional argument pixelwise non-nil means to measure the new width and height in units of pixels instead. Note that if frame-resize-pixelwise is nil, some toolkits may refuse to truly honor the request if it does not increase/decrease the frame size to a multiple of its character size.

Function: set-frame-height frame height &optional pretend pixelwise

This function resizes the text area of frame to a height of height lines. The sizes of existing windows in frame are altered proportionally to fit.

If pretend is non-nil, then Emacs displays height lines of output in frame, but does not change its value for the actual height of the frame. This is only useful on text terminals. Using a smaller height than the terminal actually implements may be useful to reproduce behavior observed on a smaller screen, or if the terminal malfunctions when using its whole screen. Setting the frame height directly does not always work, because knowing the correct actual size may be necessary for correct cursor positioning on text terminals.

The optional fourth argument pixelwise non-nil means that frame should be height pixels high. Note that if frame-resize-pixelwise is nil, some window managers may refuse to truly honor the request if it does not increase/decrease the frame height to a multiple of its character height.

Function: set-frame-width frame width &optional pretend pixelwise

This function sets the width of the text area of frame, measured in characters. The argument pretend has the same meaning as in set-frame-height.

The optional fourth argument pixelwise non-nil means that frame should be width pixels wide. Note that if frame-resize-pixelwise is nil, some window managers may refuse to fully honor the request if it does not increase/decrease the frame width to a multiple of its character width.

None of these three functions will make a frame smaller than needed to display all of its windows together with their scroll bars, fringes, margins, dividers, mode and header lines. This contrasts with requests by the window manager triggered, for example, by dragging the external border of a frame with the mouse. Such requests are always honored by clipping, if necessary, portions that cannot be displayed at the right, bottom corner of the frame. The parameters min-width and min-height (see section サイズのパラメーター) can be used to obtain a similar behavior when changing the frame size from within Emacs.

The abnormal hook window-size-change-functions (see section ウィンドウのスクロールと変更のためのフック) tracks all changes of the inner size of a frame including those induced by request of the window-system or window manager. To rule out false positives that might occur when changing only the sizes of a frame’s windows without actually changing the size of the inner frame, use the following function.

Function: frame-size-changed-p &optional frame: This function returns non-nil when the inner width or height of frame has changed since window-size-change-functions was run the last time for frame. It always returns nil immediately after running window-size-change-functions for frame.

29.3.5 Implied Frame Resizing

By default, Emacs tries to keep the number of lines and columns of a frame’s text area unaltered when, for example, adding or removing the menu bar, changing the default font or setting the width of the frame’s scroll bars. This means, however, that in such case Emacs must ask the window manager to resize the outer frame in order to accommodate the size change. Note that wrapping a menu or tool bar usually does not resize the frame’s outer size, hence this will alter the number of displayed lines.

Occasionally, such implied frame resizing may be unwanted, for example, when the frame is maximized or made full-screen (where it’s turned off by default). In other cases you can disable implied resizing with the following option:

User Option: frame-inhibit-implied-resize

If this option is nil, changing font, menu bar, tool bar, internal borders, fringes or scroll bars of a specific frame may implicitly resize the frame’s display area in order to preserve the number of columns or lines the frame displays. If this option is non-nil, no implied resizing is done.

The value of this option can be also a list of frame parameters. In that case, implied resizing is inhibited when changing a parameter that appears in this list. The frame parameters currently handled by this option are: font, font-backend, internal-border-width, menu-bar-lines and tool-bar-lines.

Changing any of the scroll-bar-width, scroll-bar-height, vertical-scroll-bars, horizontal-scroll-bars, left-fringe and right-fringe frame parameters is handled as if the frame contained just one live window. This means, for example, that removing vertical scroll bars on a frame containing several side by side windows will shrink the outer frame width by the width of one scroll bar provided this option is nil and keep it unchanged if this option is either t or a list containing vertical-scroll-bars.

The default value is '(tool-bar-lines) for Lucid, Motif and MS-Windows (which means that adding/removing a tool bar there does not change the outer frame height), nil on all other window systems including GTK+ (which means that changing any of the parameters listed above may change the size of the outer frame), and t otherwise (which means the outer frame size never changes implicitly when there’s no window system support).

Note that when a frame is not large enough to accommodate a change of any of the parameters listed above, Emacs may try to enlarge the frame even if this option is non-nil.

29.4 フレームのパラメーター

フレームはに、その外見と挙動を制御する、多くのパラメーターがあります。フレームがどのようなパラメーターをもつかは、そのフレームが使用するディスプレイのメカニズムに依存します。

フレームパラメーターは主に、グラフィカルディスプレイのために存在します。ほとんどのフレームパラメーターは、テキスト端末上のフレームに適用時は効果がありません。テキスト端末上のフレームでは、何か特別なことを行うパラメーターはheight、width、name、title、menu-bar-lines、buffer-list、buffer-predicateだけです。その端末がカラーをサポートにはforeground-color、background-color、background-mode、display-typeなどのパラメーターも意味をもちます。その端末が透過フレーム(frame transparency)をサポートする場合には、パラメーターalphaも意味をもちます。

By default, frame parameters are saved and restored by the desktop library functions (see section Desktop Saveモード) when the variable desktop-restore-frames is non-nil. It’s the responsibility of applications that their parameters are included in frameset-persistent-filter-alist to avoid that they get meaningless or even harmful values in restored sessions.

29.4.1 フレームパラメーターへのアクセス

以下の関数により、フレームのパラメーター値の読み取りと変更ができます。

Function: frame-parameter frame parameter: この関数は、frameのパラメーターparameter(シンボル)の値をリターンする。frameがnilなら、選択されたフレームのパラメーターをリターンする。frameがparameterにたいするセッティングをもたない場合、この関数はnilをリターンする。

Function: frame-parameters &optional frame: 関数frame-parametersは、frameのすべてのパラメーターとその値をリストするalistをリターンする。frameが省略またはnilの場合は、選択されたフレームのパラメーターをリターンする。

Function: modify-frame-parameters frame alist

This function alters the frame frame based on the elements of alist. Each element of alist has the form (parm . value), where parm is a symbol naming a parameter. If you don’t mention a parameter in alist, its value doesn’t change. If frame is nil, it defaults to the selected frame.

Some parameters are only meaningful for frames on certain kinds of display (see section フレーム). If alist includes parameters that are not meaningful for the frame’s display, this function will change its value in the frame’s parameter list, but will otherwise ignore it.

When alist specifies more than one parameter whose value can affect the new size of frame, the final size of the frame may differ according to the toolkit used. For example, specifying that a frame should from now on have a menu and/or tool bar instead of none and simultaneously specifying the new height of the frame will inevitably lead to a recalculation of the frame’s height. Conceptually, in such case, this function will try to have the explicit height specification prevail. It cannot be excluded, however, that the addition (or removal) of the menu or tool bar, when eventually performed by the toolkit, will defeat this intention.

Sometimes, binding frame-inhibit-implied-resize (see section Implied Frame Resizing) to a non-nil value around calls to this function may fix the problem sketched here. Sometimes, however, exactly such binding may be hit by the problem.

Function: set-frame-parameter frame parm value: この関数は、フレームパラメーターparmに、指定されたvalueをセットする。frameがnilの場合のデフォルトは、選択されたフレームである。

Function: modify-all-frames-parameters alist: この関数は、 alistに応じて既存のフレームすべてのフレームパラメーターを変更してから、今後に作成されるフレームに同じパラメーター値を適用するために、default-frame-alist(と必要ならinitial-frame-alist)を変更する。

29.4.2 フレームの初期パラメーター

initファイル(initファイルを参照)内でinitial-frame-alistをセットすることにより、フレームの初期スタートアップにパラメーターを指定できます。

User Option: initial-frame-alist

この変数の値は、初期フレーム作成時に使用されるパラメーター値のalistである。以降のフレームを変更することなく、初期フレームの外見を指定するために、この変数を使用できる。要素はそれぞれ以下の形式をもつ:

(parameter . value)

Emacsは、initファイル読み取り前に初期フレームを作成する。After reading that file, Emacs checks initial-frame-alistをチェックして、すでに作成済みの初期フレームに、変更する値に含まれるパラメーターのセッティングを適用する。

これらのセッティングがフレームのジオメトリーと外見に影響する場合には、間違った外見のフレームを見た後、指定した外見に変更されるのを目にするだろう。これが煩わしい場合は、Xリソースで同じジオメトリーと外見を指定できる。これらは、フレーム作成前に効果をもつ。X Resources in The GNU Emacs Manualを参照されたい。

Xリソースセッティングは通常、すべての!に適用される。初期フレームのために、あるXリソースを単独で指定して、それ以降のフレームには適用したくない場合は、次の方法によりこれを達成できる。それ以降のフレームにたいするXリソースをオーバーライドするために、default-frame-alist内でパラメーターを指定してから、それらが初期フレームに影響するのを防ぐために、initial-frame-alist内の同じパラメーターにたいして、Xリソースにマッチする値を指定すればよい。

これらのパラメーターに(minibuffer . nil)が含まれるなら、それは初期フレームがミニバッファーをもつべきではないことを示します。この場合、Emacsは同じようにミニバッファーオンリーフレーム(minibuffer-only frame)を別個作成します。

User Option: minibuffer-frame-alist: この変数の値は、初期ミニバッファーオンリーフレーム(initial-frame-alistがミニバッファーのないフレームを指定する場合にEmacsが作成するミニバッファーオンリーフレームのこと)を作成時に使用されるパラメーター値のalistである。

User Option: default-frame-alist

これは、すべてのEmacsフレーム(最初のフレームとそれ以降のフレーム)にたいして、フレームパラメーターのデフォルト値を指定するalistである。Xウィンドウシステム使用時には、大抵はXリソースで同じ結果を得られる。

この変数のセットは既存フレームに影響しない。さらに、別フレームにバッファーを表示する関数は、自身のパラメーターを提供することにより、デフォルトパラメーターをオーバーライドできる。

フレームの外見を指定するコマンドラインオプションとともにEmacsを呼び出した場合、これらのオプションはinitial-frame-alistまたはdefault-frame-alistのいずれかに要素を追加することにより、効果を発揮します。‘--geometry’や‘--maximized’のような、初期フレームだけに影響するオプションはinitial-frame-alist、その他のオプションはdefault-frame-alistに要素を追加します。Command Line Arguments for Emacs Invocation in The GNU Emacs Manualを参照してください。

29.4.3 ウィンドウフレームパラメーター

フレームがどんなパラメーターをもつかは、どのようなディスプレイのメカニズムがそれを使用するかに依存します。このセクションでは、一部、またはすべての端末種類において特別な意味をもつパラメーターを説明します。これらのうちname、title、height、width、buffer-list、buffer-predicateは端末フレームにおいて有意な情報を提供し、tty-color-modeはテキスト端末上のフレームにたいして意味があります。

29.4.3.1 基本パラメーター		基本的なパラメーター。
29.4.3.2 位置のパラメーター		スクリーン上のフレームの位置。
29.4.3.3 サイズのパラメーター		フレームのサイズ。
29.4.3.4 レイアウトのパラメーター		フレームのパーツのサイズと、一部パーツの有効化と無効化。
29.4.3.5 バッファーのパラメーター		表示済みまたは表示されるべきバッファーはどれか。
29.4.3.6 Frame Interaction Parameters		Parameters for interacting with other frames.
29.4.3.7 Mouse Dragging Parameters		Parameters for resizing and moving frames with the mouse.
29.4.3.8 ウィンドウ管理のパラメーター		ウィンドウマネージャーとの対話。
29.4.3.9 カーソルのパラメーター		カーソルの外見の制御。
29.4.3.10 フォントとカラーのパラメーター		フレームテキストにたいするフォントとカラー。

29.4.3.1 基本パラメーター

以下のフレームパラメーターは、フレームに関してもっとも基本的な情報を提供します。titleとnameは、すべての端末において意味をもちます。

display

このフレームをオープンするためのディスプレイ。これは環境変数DISPLAYのような、‘host:dpy.screen’という形式の文字列であること。ディスプレイ名についての詳細は、See section 複数の端末を参照のこと。

display-type

このパラメーターは、このフレーム内で使用できる利用可能なカラーの範囲を記述する。値はcolor、grayscale、monoのいずれか。

title

フレームが非nilのtitleをもつ場合、それはフレーム上端にあるウィンドウシステムのタイトルバーに表示され、mode-line-frame-identificationに‘%F’(モードラインでの%構造を参照)を使用していればそのフレーム内のウィンドウのモードラインにも表示される。これは通常、Emacsがウィンドウシステムを使用しておらず、かつ同時に1つのフレームのみ表示可能なケースが該当する。フレームのタイトルを参照のこと。

name

そのフレームの名前。titleが未指定またはnilなら、フレーム名はフレームタイトルにたいしてデフォルトの役割りを果たす。nameを指定しない場合、Emacsは自動的にフレーム名をセットする(フレームのタイトルを参照)。

フレーム作成時に明示的にフレーム名を指定した場合は、そのフレームにたいしてXリソースを照合する際にも、(Emacs実行可能形式名のかわりに)その名前が使用される。

explicit-name

フレーム作成時にフレーム名が明示的に指定された場合、このパラメーターはその名前になるだろう。明示的に名付けられなかった場合、このパラメーターはnilになる。

29.4.3.2 位置のパラメーター

Parameters describing the X- and Y-offsets of a frame are always measured in pixels. For a normal, non-child frame they specify the frame’s outer position (see section Frame Geometry) relative to its display’s origin. For a child frame (see section Child Frames) they specify the frame’s outer position relative to the native position of the frame’s parent frame. (Note that none of these parameters is meaningful on TTY frames.)

left

The position, in pixels, of the left outer edge of the frame with respect to the left edge of the frame’s display or parent frame. It can be specified in one of the following ways.

整数

A positive integer always relates the left edge of the frame to the left edge of its display or parent frame. A negative integer relates the right frame edge to the right edge of the display or parent frame.

(+ pos)

This specifies the position of the left frame edge relative to the left edge of its display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).

(- pos)

This specifies the position of the right frame edge relative to the right edge of the display or parent frame. The integer pos may be positive or negative; a negative value specifies a position outside the screen or parent frame or on a monitor other than the primary one (for multi-monitor displays).

a floating-point value

A floating-point value in the range 0.0 to 1.0 specifies the left edge’s offset via the left position ratio of the frame—the ratio of the left edge of its outer frame to the width of the frame’s workarea (see section 複数の端末) or its parent’s native frame (see section Child Frames) minus the width of the outer frame. Thus, a left position ratio of 0.0 flushes a frame to the left, a ratio of 0.5 centers it and a ratio of 1.0 flushes it to the right of its display or parent frame. Similarly, the top position ratio of a frame is the ratio of the frame’s top position to the height of its workarea or parent frame minus the height of the frame.

Emacs will try to keep the position ratios of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see section Frame Interaction Parameters) and its parent frame is resized.

Since the outer size of a frame (see section Frame Geometry) is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited for ensuring that an (undecorated) child frame is positioned nicely within the area of its parent frame.

Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a non-nil value for the user-position parameter as in the following example:

(modify-frame-parameters
  nil '((user-position . t) (left . (+ -4))))

In general, it is not a good idea to position a frame relative to the right or bottom edge of its display. Positioning the initial or a new frame is either not accurate (because the size of the outer frame is not yet fully known before the frame has been made visible) or will cause additional flicker (if the frame has to be repositioned after becoming visible).

Note also, that positions specified relative to the right/bottom edge of a display, workarea or parent frame as well as floating-point offsets are stored internally as integer offsets relative to the left/top edge of the display, workarea or parent frame edge. They are also returned as such by functions like frame-parameters and restored as such by the desktop saving routines.

top

The screen position of the top (or bottom) edge, in pixels, with respect to the top (or bottom) edge of the display or parent frame. It works just like left, except vertically instead of horizontally.

icon-left

スクリーン左端から数えた、フレームアイコン左端のピクセル単位のスクリーン位置。ウィンドウマネージャーがこの機能をサポートすれば、これはフレームをアイコン化したとき効果を発揮する。このパラメーターに値を指定する場合はicon-topにも値を指定しなければならず、その逆も真である。

icon-top

スクリーン上端から数えた、フレームアイコン上端のピクセル単位のスクリーン位置。ウィンドウマネージャーがこの機能をサポートすれば、これはフレームをアイコン化したとき効果を発揮する。

user-position

フレームを作成してパラメーターleftとtopで位置を指定する際は、指定した位置がユーザー指定(人間であるユーザーにより明示的に要求された位置)なのか、それとも単なるプログラム指定(プログラムにより選択された位置)なのかを告げるために、このパラメーターを使用する。非nil値は、それがユーザー指定の位置であることを告げる。

ウィンドウマネージャーは一般的にユーザー指定位置に留意し、プログラム指定位置にも幾分か留意する。しかし、多くはプログラム指定位置を無視してウィンドウをウィンドウマネージャーのデフォルトの方法で配すか、ユーザーのマウスによる配置に任せる。twmを含むウィンドウマネージャーのいくつかは、プログラム指定位置にしたがうか無視するかをユーザーの指定に任せる。

make-frameを呼び出す際、パラメーターleftおよびtopの値がそのユーザーにより示される嗜好を表すなら、このパラメーターに非nil値を、それ以外はnilを指定するべきである。

z-group

This parameter specifies a relative position of the frame’s window-system window in the stacking (Z-) order of the frame’s display.

If this is above, the frame’s window-system window is displayed above all other window-system windows that do not have the above property set. If this is nil, the frame’s window is displayed below all windows that have the above property set and above all windows that have the below property set. If this is below, the frame’s window is displayed below all windows that do not have the below property set.

To position the frame above or below a specific other frame use the function frame-restack (see section Raising, Lowering and Restacking Frames).

29.4.3.3 サイズのパラメーター

Frame parameters usually specify frame sizes in character units. On graphical displays, the default face determines the actual pixel sizes of these character units (see section フェイスの属性).

width

This parameter specifies the width of the frame. It can be specified as in the following ways:

整数

A positive integer specifies the width of the frame’s text area (see section Frame Geometry) in characters.

a cons cell

If this is a cons cell with the symbol text-pixels in its CAR, the CDR of that cell specifies the width of the frame’s text area in pixels.

a floating-point value

A floating-point number between 0.0 and 1.0 can be used to specify the width of a frame via its width ratio—the ratio of its outer width (see section Frame Geometry) to the width of the frame’s workarea (see section 複数の端末) or its parent frame’s (see section Child Frames) native frame. Thus, a value of 0.5 makes the frame occupy half of the width of its workarea or parent frame, a value of 1.0 the full width. Similarly, the height ratio of a frame is the ratio of its outer height to the height of its workarea or its parent’s native frame.

Emacs will try to keep the width and height ratio of a child frame unaltered if that frame has a non-nil keep-ratio parameter (see section Frame Interaction Parameters) and its parent frame is resized.

Since the outer size of a frame is usually unavailable before a frame has been made visible, it is generally not advisable to use floating-point values when creating decorated frames. Floating-point values are more suited to ensure that a child frame always fits within the area of its parent frame as, for example, when customizing display-buffer-alist (see section 表示するウィンドウの選択) via display-buffer-in-child-frame.

Regardless of how this parameter was specified, functions reporting the value of this parameter like frame-parameters always report the width of the frame’s text area in characters as an integer rounded, if necessary, to a multiple of the frame’s default character width. That value is also used by the desktop saving routines.

height

This parameter specifies the height of the frame. It works just like width, except vertically instead of horizontally.

user-size

これは、サイズパラメーターheightおよびwidthにたいして、user-position(user-positionを参照)がtopおよびleftが行うのと同じことを行う。

min-width

This parameter specifies the minimum native width (see section Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial width or resize a frame horizontally make sure that all the frame’s windows, vertical scroll bars, fringes, margins and vertical dividers can be displayed. This parameter, if non-nil allows to make a frame narrower than that with the consequence that any components that do not fit will be clipped by the window manager.

min-height

This parameter specifies the minimum native height (see section Frame Geometry) of the frame, in characters. Normally, the functions that establish a frame’s initial size or resize a frame make sure that all the frame’s windows, horizontal scroll bars and dividers, mode and header lines, the echo area and the internal menu and tool bar can be displayed. This parameter, if non-nil allows to make a frame smaller than that with the consequence that any components that do not fit will be clipped by the window manager.

fullscreen

This parameter specifies whether to maximize the frame’s width, height or both. Its value can be fullwidth, fullheight, fullboth, or maximized. A fullwidth frame is as wide as possible, a fullheight frame is as tall as possible, and a fullboth frame is both as wide and as tall as possible. A maximized frame is like a “fullboth” frame, except that it usually keeps its title bar and the buttons for resizing and closing the frame. Also, maximized frames typically avoid hiding any task bar or panels displayed on the desktop. A “fullboth” frame, on the other hand, usually omits the title bar and occupies the entire available screen space.

Full-height and full-width frames are more similar to maximized frames in this regard. However, these typically display an external border which might be absent with maximized frames. Hence the heights of maximized and full-height frames and the widths of maximized and full-width frames often differ by a few pixels.

With some window managers you may have to customize the variable frame-resize-pixelwise (see section Frame Size) in order to make a frame truly appear maximized or full-screen. Moreover, some window managers might not support smooth transition between the various full-screen or maximization states. Customizing the variable x-frame-normalize-before-maximize can help to overcome that.

Full-screen on macOS hides both the tool-bar and the menu-bar, however both will be displayed if the mouse pointer is moved to the top of the screen.

fullscreen-restore

This parameter specifies the desired fullscreen state of the frame after invoking the toggle-frame-fullscreen command (see Frame Commands in The GNU Emacs Manual) in the “fullboth” state. Normally this parameter is installed automatically by that command when toggling the state to fullboth. If, however, you start Emacs in the “fullboth” state, you have to specify the desired behavior in your initial file as, for example

(setq default-frame-alist
    '((fullscreen . fullboth)
      (fullscreen-restore . fullheight)))

This will give a new frame full height after typing in it F11 for the first time.

fit-frame-to-buffer-margins

This parameter allows to override the value of the option fit-frame-to-buffer-margins when fitting this frame to the buffer of its root window with fit-frame-to-buffer (see section ウィンドウのリサイズ).

fit-frame-to-buffer-sizes

This parameter allows to override the value of the option fit-frame-to-buffer-sizes when fitting this frame to the buffer of its root window with fit-frame-to-buffer (see section ウィンドウのリサイズ).

29.4.3.4 レイアウトのパラメーター

以下のフレームパラメーターにより、フレームのさまざまなパーツを有効または無効にしたり、サイズを制御できます。

border-width

The width in pixels of the frame’s outer border (see section Frame Geometry).

internal-border-width

The width in pixels of the frame’s internal border (see section Frame Geometry).

vertical-scroll-bars

Whether the frame has scroll bars (see section スクロールバー) for vertical scrolling, and which side of the frame they should be on. The possible values are left, right, and nil for no scroll bars.

horizontal-scroll-bars

Whether the frame has scroll bars for horizontal scrolling (t and bottom mean yes, nil means no).

scroll-bar-width

垂直スクロールバーのピクセル単位による幅。nilはデフォルト幅の使用を意味する。

scroll-bar-height

The height of horizontal scroll bars, in pixels, or nil meaning to use the default height.

left-fringe

right-fringe

そのフレーム内のウィンドウの左右フリンジのデフォルト幅(フリンジを参照)。いずれかが0なら、対応するフリンジを削除する効果がある。 If either of these is zero, that effectively removes the corresponding fringe.

これら2つのフレームパラメーターの値を問い合わせるためにframe-parameterを使用する際、リターン値は常に整数となる。nil値を渡してset-frame-parameterを使用する際は、実際のデフォルト値8ピクセルが課せられる。

right-divider-width

フレーム上のすべてのウィンドウの右ディバイダー(ウィンドウディバイダーを参照)用に予約される、ピクセル単位の幅(厚さ)。値0は右ディバイダーを描画しないことを意味する。

bottom-divider-width

フレーム上のすべてのウィンドウの下ディバイダー(ウィンドウディバイダーを参照)用に予約される、ピクセル単位の幅(厚さ)。値0は下ディバイダーを描画しないことを意味する。

menu-bar-lines

The number of lines to allocate at the top of the frame for a menu bar (see section メニューバー Bar). The default is one if Menu Bar mode is enabled and zero otherwise. See Menu Bars in The GNU Emacs Manual. For an external menu bar (see section Frame Layout), this value remains unchanged even when the menu bar wraps to two or more lines. In that case, the menu-bar-size value returned by frame-geometry (see section Frame Geometry) allows to derive whether the menu bar actually occupies one or more lines.

tool-bar-lines

The number of lines to use for the tool bar (see section ツールバー). The default is one if Tool Bar mode is enabled and zero otherwise. See Tool Bars in The GNU Emacs Manual. This value may change whenever the tool bar wraps (see section Frame Layout).

tool-bar-position

The position of the tool bar when Emacs was built with GTK+. Its value can be one of top, bottom left, right. The default is top.

line-spacing

各テキスト行配下に残す、ピクセル単位の追加スペース(正の整数)。詳細は行の高さを参照のこと。

no-special-glyphs

If this is non-nil, it suppresses the display of any truncation and continuation glyphs (see section 切り詰め) for all buffers displayed by this frame. This is useful to eliminate such glyphs when fitting a frame to its buffer via fit-frame-to-buffer (see section ウィンドウのリサイズ).

29.4.3.5 バッファーのパラメーター

以下は、フレーム内でどのバッファーが表示されているか、されるべきかを扱うためのフレームパラメーターで、すべての種類の端末上で意味があります。

minibuffer

そのフレームが自身のミニバッファーをもつか否か。もつ場合はt、もたない場合はnil、onlyならそのフレームが正にミニバッファーであることを意味する。値が(別フレーム内の)ミニバッファーウィンドウの場合、そのフレームはそのミニバッファーを使用する。

This parameter takes effect when the frame is created. If specified as nil, Emacs will try to set it to the minibuffer window of default-minibuffer-frame (see section ミニバッファーとフレーム). For an existing frame, this parameter can be used exclusively to specify another minibuffer window. It is not allowed to change it from a minibuffer window to t and vice-versa, or from t to nil. If the parameter specifies a minibuffer window already, setting it to nil has no effect.

buffer-predicate

このフレームにたいする、buffer-predicate関数。関数other-bufferは、どのバッファーを考慮すべきか決定するために、(選択されたフレームから)この述語がnilでなければ、これを使用する。これは各バッファーにたいして、そのバッファーを唯一の引数として、この述語を1回呼び出す。この述語が非nil値をリターンしたら、そのバッファーは考慮される。

buffer-list

そのフレーム内で選択されているバッファーの、もっとも最近選択されたバッファーが先頭になるような順のリスト。

unsplittable

非nilなら、このフレームのウィンドウは決して自動的に分割されることはない。

29.4.3.6 Frame Interaction Parameters

These parameters supply forms of interactions between different frames.

parent-frame

If non-nil, this means that this frame is a child frame (see section Child Frames), and this parameter specifies its parent frame. If nil, this means that this frame is a normal, top-level frame.

delete-before

If non-nil, this parameter specifies another frame whose deletion will automatically trigger the deletion of this frame. See section フレームの削除.

mouse-wheel-frame

If non-nil, this parameter specifies the frame whose windows will be scrolled whenever the mouse wheel is scrolled with the mouse pointer hovering over this frame, see Mouse Commands in The GNU Emacs Manual.

no-other-frame

If this is non-nil, then this frame is not eligible as candidate for the functions next-frame, previous-frame (see section すべてのフレームを探す) and other-frame, see Frame Commands in The GNU Emacs Manual.

auto-hide-function

When this parameter specifies a function, that function will be called instead of the function specified by the variable frame-auto-hide-function when quitting the frame’s only window (see section ウィンドウのquit) and there are other frames left.

minibuffer-exit

When this parameter is non-nil, Emacs will by default make this frame invisible whenever the minibuffer (see section ミニバッファー) is exited. Alternatively, it can specify the functions iconify-frame and delete-frame. This parameter is useful to make a child frame disappear automatically (similar to how Emacs deals with a window) when exiting the minibuffer.

keep-ratio

This parameter is currently meaningful for child frames (see section Child Frames) only. If it is non-nil, then Emacs will try to keep the frame’s size (width and height) ratios (see section サイズのパラメーター) as well as its left and right position ratios (see section 位置のパラメーター) unaltered whenever its parent frame is resized.

If the value of this parameter is nil, the frame’s position and size remain unaltered when the parent frame is resized, so the position and size ratios may change. If the value of this parameter is t, Emacs will try to preserve the frame’s size and position ratios, hence the frame’s size and position relative to its parent frame may change.

More individual control is possible by using a cons cell: In that case the frame’s width ratio is preserved if the CAR of the cell is either t or width-only. The height ratio is preserved if the CAR of the cell is either t or height-only. The left position ratio is preserved if the CDR of the cell is either t or left-only. The top position ratio is preserved if the CDR of the cell is either t or top-only.

29.4.3.7 Mouse Dragging Parameters

The parameters described below provide support for resizing a frame by dragging its internal borders with the mouse. They also allow moving a frame with the mouse by dragging the header line of its topmost or the mode line of its bottommost window.

These parameters are mostly useful for child frames (see section Child Frames) that come without window manager decorations. If necessary, they can be used for undecorated top-level frames as well.

drag-internal-border: If non-nil, the frame can be resized by dragging its internal borders, if present, with the mouse.
drag-with-header-line: If non-nil, the frame can be moved with the mouse by dragging the header line of its topmost window.
drag-with-mode-line: If non-nil, the frame can be moved with the mouse by dragging the mode line of its bottommost window. Note that such a frame is not allowed to have its own minibuffer window.
snap-width: A frame that is moved with the mouse will “snap” at the border(s) of the display or its parent frame whenever it is dragged as near to such an edge as the number of pixels specified by this parameter.
top-visible: If this parameter is a number, the top edge of the frame never appears above the top edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-header-line parameter completely out of the area of its parent frame.
bottom-visible: If this parameter is a number, the bottom edge of the frame never appears below the bottom edge of its display or parent frame. Moreover, as many pixels of the frame as specified by that number will remain visible when the frame is moved against any of the remaining edges of its display or parent frame. Setting this parameter is useful to guard against dragging a child frame with a non-nil drag-with-mode-line parameter completely out of the area of its parent frame.

29.4.3.8 ウィンドウ管理のパラメーター

The following frame parameters control various aspects of the frame’s interaction with the window manager or window system. They have no effect on text terminals.

visibility

フレームの可視性(visibility)の状態。可能な値は3つあり、nilは不可視、tは可視、iconはアイコン化されていることを意味する。フレームの可視性を参照のこと。

auto-raise

非nilなら、Emacsはそのフレーム選択時に自動的にそれを前面に移動(raise)する。これを許さないウィンドウマネージャーがいくつかある。

auto-lower

非nilなら、Emacsはそのフレームの選択解除時に自動的にそれを背面に移動(lower)する。これを許さないウィンドウマネージャーがいくつかある。

icon-type

そのフレームに使用するアイコンのタイプ。値が文字列の場合、それは使用するビットマップを含むファイルを指定し、nilはアイコンなしを指定する(何を表示するかはウィンドウマネージャーが決定する)。その他の非nil値は、デフォルトのEmacsアイコンを指定する。

icon-name

このフレームにたいするアイコンで使用する名前。アイコンを表示する場合は、その際に表示される。これがnilなら、フレームのタイトルが使用される。

window-id

グラフィカルディスプレイがこのフレームにたいして使用するID番号。Emacsは、フレーム作成時にこのパラメーターを割り当てる。このパラメーターを変更しても、実際のID番号に効果はない。

outer-window-id

そのフレームが存在する最外殻のウィンドウシステムのウィンドウのID番号。window-idと同様、このパラメーターを変更しても実際の効果はない。

wait-for-wm

非nilなら、ジオメトリー変更を確認するために、ウィンドウマネージャーを待機するようXtに指示する。Fvwm2およびKDEのバージョンを含むウィンドウマネージャーのいくつかは確認に失敗するので、Xtがハングする。これらウィンドウマネージャーのハングを防ぐために、これをnilにセットする。

sticky

非nilなら、仮想デスクトップを伴うシステム上のすべての仮想デスクトップ上で、そのフレームが可視になる。

inhibit-double-buffering

If non-nil, the frame is drawn to the screen without double buffering. Emacs normally attempts to use double buffering, where available, to reduce flicker. Set this property if you experience display bugs or pine for that retro, flicker-y feeling.

skip-taskbar

If non-nil, this tells the window manager to remove the frame’s icon from the taskbar associated with the frame’s display and inhibit switching to the frame’s window via the combination Alt-TAB. On MS-Windows, iconifying such a frame will "roll in" its window-system window at the bottom of the desktop. Some window managers may not honor this parameter.

no-focus-on-map

If non-nil, this means that the frame does not want to receive input focus when it is mapped (see section フレームの可視性). Some window managers may not honor this parameter.

no-accept-focus

If non-nil, this means that the frame does not want to receive input focus via explicit mouse clicks or when moving the mouse into it either via focus-follows-mouse (see section 入力のフォーカス) or mouse-autoselect-window (see section Mouse Window Auto-selection). This may have the unwanted side-effect that a user cannot scroll a non-selected frame with the mouse. Some window managers may not honor this parameter.

undecorated

If non-nil, this frame’s window-system window is drawn without decorations, like the title, minimize/maximize boxes and external borders. This usually means that the window cannot be dragged, resized, iconified, maximized or deleted with the mouse. If nil, the frame’s window is usually drawn with all the elements listed above unless their display has been suspended via window manager settings.

Under X, Emacs uses the Motif window manager hints to turn off decorations. Some window managers may not honor these hints.

NS builds consider the tool bar to be a decoration, and therefore hide it on an undecorated frame.

override-redirect

If non-nil, this means that this is an override redirect frame—a frame not handled by window managers under X. Override redirect frames have no window manager decorations, can be positioned and resized only via Emacs’ positioning and resizing functions and are usually drawn on top of all other frames. Setting this parameter has no effect on MS-Windows.

ns-appearance

Only available on macOS, if set to dark draw this frame’s window-system window using the “vibrant dark” theme, otherwise use the system default. The “vibrant dark” theme can be used to set the toolbar and scrollbars to a dark appearance when using an Emacs theme with a dark background.

ns-transparent-titlebar

Only available on macOS, if non-nil, set the titlebar and toolbar to be transparent. This effectively sets the background color of both to match the Emacs background color.

29.4.3.9 カーソルのパラメーター

このフレームパラメーター!、カーソルの外見を制御します。

cursor-type

カーソルの表示方法。適正な値は:

box: 塗りつぶされた四角形(filled box)を表示する(デフォルト)。
hollow: 中抜きの四角形(hollow box)を表示する。
nil: カーソルウィンドウ表示しない。
bar: 文字間に垂直バー(vertical bar)を表示する。
(bar . width): 文字間に幅がwidthピクセルの垂直バー(vertical bar)を表示する。
hbar: 文字間に水平バー(horizontal bar)を表示する。
(hbar . height): 文字間に高さがheightピクセルの水平バー(horizontal bar)を表示する。

フレームパラメーターcursor-typeは、変数cursor-typeおよびcursor-in-non-selected-windowsによりオーバーライドされるかもしれません。

User Option: cursor-type: このバッファーローカル変数は、選択されたウィンドウ内で表示されているそのバッファーのカーソルの外見を制御する。この値がtなら、それはフレームパラメーターcursor-typeで指定されたカーソルのーを使用することを意味する。それ以外では、値は上記リストのカーソルタイプのいずれかであるべきで、これはフレームパラメーターcursor-typeをオーバーライドする。

User Option: cursor-in-non-selected-windows: このバッファーローカル変数は、選択されていないウィンドウ内でのカーソルの外見を制御する。これは、フレームパラメーターcursor-typeと同じ値をサポートする。さらに、nilは選択されていないウィンドウ内にはカーソルを表示せず、tは通常のカーソルタイプの標準的な変更(塗りつぶされた四角形は中抜きの四角形に、バーはより細いバーにする)の使用を意味する。

User Option: x-stretch-cursor

This variable controls the width of the block cursor displayed on extra-wide glyphs such as a tab or a stretch of white space. By default, the block cursor is only as wide as the font’s default character, and will not cover all of the width of the glyph under it if that glyph is extra-wide. A non-nil value of this variable means draw the block cursor as wide as the glyph under it. The default value is nil.

This variable has no effect on text-mode frames, since the text-mode cursor is drawn by the terminal out of Emacs’s control.

User Option: blink-cursor-alist

This variable specifies how to blink the cursor. Each element has the form (on-state . off-state). Whenever the cursor type equals on-state (comparing using equal), the corresponding off-state specifies what the cursor looks like when it blinks off. Both on-state and off-state should be suitable values for the cursor-type frame parameter.

それぞれのカーソルタイプのブリンク方法にたいして、そのタイプがここでon-stateとして指定されていなければ、さまざまなデフォルトが存在する。フレームパラメーターcursor-typeで指定した際に限り、この変数内での変更は即座に効果を発揮しない。

29.4.3.10 フォントとカラーのパラメーター

以下のフレームパラメーターは、フォントとカラーの使用を制御します。

font-backend

フレーム内でフォントの描画に使用するためのフォントバックエンド(font backends)を指定する、優先順のシンボルのリスト。Xでは現在のところ、x(X core font driver)とxft(Xft font driver)の2つの利用可能なフォントバックエンドがある。MS-Windowsでは現在のところ、gdiとuniscribeの2つの利用可能なフォントバックエンドがある(Windows Fonts in The GNU Emacs Manualを参照)。その他のシステムでは利用可能なフォントバックエンドは1つだけなので、このフレームパラメーターを変更しても意味がない。

background-mode

このパラメーターはdarkかlightのいずれかで、それぞれバックグラウンドを暗く(dark)するか、明るく(light)するかに対応する。

tty-color-mode

This parameter overrides the terminal’s color support as given by the system’s terminal capabilities database in that this parameter’s value specifies the color mode to use on a text terminal. The value can be either a symbol or a number. A number specifies the number of colors to use (and, indirectly, what commands to issue to produce each color). For example, (tty-color-mode . 8) specifies use of the ANSI escape sequences for 8 standard text colors. A value of -1 turns off color support.

このパラメーターの値がシンボルの場合、それはtty-color-mode-alistの値を通じた数値を指定するもので、かわりにそのシンボルに割り当てられた数値が使用される。

screen-gamma

If this is a number, Emacs performs gamma correction which adjusts the brightness of all colors. The value should be the screen gamma of your display.

通常のPCモニター／あスクリーンガンマが2.2なので、EmacsおよびXウィンドウのカラー値は一般的にそのガンマ値のモニター上で正しく表示するよう校正されている。screen-gammaにたいして2.2を指定した場合、それは補正が不必要であることを意味する。その他の値は、通常のモニター上でガンマ値2.2で表示されるであろう、補正されたカラーがスクリーン上に表示されるように意図された補正を要求する。

モニターが表示するカラーが明るすぎる場合は、screen-gammaに2.2より小さい値を指定するべきである。これは、カラーをより暗くする補正を要求する。スクリーンガンマの値1.5は、LCDカラーディスプレイにたいして、よい結果を与えるだろう。

alpha

このパラメーターは、可変透明度(variable opacity)をサポートするグラフィカルディスプレイ上での、そのフレームの透明度を指定する(訳注: opacityを訳すと逆の不透明度だが、このような場合は一般的に透明度と訳すようなので、それに倣う)。これは0から100の整数であるべきで、0は完全な透明、100hは完全な不透明を意味する。nil値をもつこともでき、これはEmacsにフレームのopacityをセットしない(ウィンドウマネージャーに委ねる)よう告げる。

フレームが完全に見えなくなるのを防ぐために、変数frame-alpha-lower-limitは透明度の最低限度を定義する。フレームパラメーターの値がこの変数の値より小さい場合、Emacsは後者を使用する。デフォルトのframe-alpha-lower-limitは20。

The alpha frame parameter can also be a cons cell (active . inactive), where active is the opacity of the frame when it is selected, and inactive is the opacity when it is not selected.

Some window systems do not support the alpha parameter for child frames (see section Child Frames).

以下は、特定のフェイスの特定のフェイス属性と自動的に等しくなるので、凖時代遅れとなったフレームパラメーターです(Standard Faces in The Emacs Manualを参照)。

font: フレーム内でテキストを表示するためのフォントの名前。これはシステムで有効なフォント名、またはEmacsフォントセット名(フォントセットを参照)のいずれかであるような文字列である。これは、defaultフェイスのfont属性と等価である。
foreground-color: 文字のイメージに使用するカラー。これは、defaultフェイスの:foreground属性と等価である。
background-color: 文字のバックグラウンドに使用するカラー。これは、defaultフェイスの:background属性と等価である。
mouse-color: マウスポインターのカラー。これはmouseフェイスの:background属性と等価である。
cursor-color: ポイントを表示するカーソルのカラー。これは、cursorフェイスの:background属性と等価である。
border-color: これは、フレームのボーダーのカラーと等価である。これは、borderフェイスの:background属性と等価である。
scroll-bar-foreground: 非nilの場合は、スクロールバーのフォアグラウンドカラー。これは、scroll-barフェイスの:foreground属性と等価である。
scroll-bar-background: 非nilの場合は、スクロールバーのバックグラウンドカラー。これは、scroll-barフェイスの:background属性と等価である。

29.4.4 ジオメトリー

以下は、Xスタイルのウィンドウジオメトリー指定によるアクションのデータを調べる方法です:

Function: x-parse-geometry geom

関数x-parse-geometryは、標準的なXウィンドウのジオメトリー文字列を、make-frameの引数の一部として使用できるalistに変換する。

このalistはgeom内で指定されたパラメーターと、そのパラメーターに指定された値を記述する。各要素は(parameter . value)のような形式である。可能なparameterの値はleft、top、width、heightである。

サイズのパラメーターの値は整数でなければならない。位置のパラメーターleftおよびtopの名前に関しては、かわりに右端または下端の位置を示す値もいくつかあるので、完全に正確ではない。位置パラメーターにたいして可能なvalueは前述(位置のパラメーターを参照)したような整数、リスト(+ pos)、リスト(- pos)である。

以下は例である:

(x-parse-geometry "35x70+0-0")
     ⇒ ((height . 70) (width . 35)
         (top - 0) (left . 0))

29.5 端末のパラメーター

端末はそれぞれ、関連するパラメーターのリストをもっています。これら端末パラメーター(terminal parameters)は主に、端末ローカル変数を格納するための便利な手段ですが、いくつかの端末パラメーターは特別な意味をもっています。

このセクションでは、端末のパラメーター値の読み取りや変更を行う関数を説明します。これらはすべて引数として端末かフレームいずれかを受け入れます。フレームの場合、それはそのフレームの端末の使用を意味します。引数nilは、選択されたフレームの端末という意味です。

Function: terminal-parameters &optional terminal: この関数は、terminalnのすべてのパラメーターとその値をリストするalistをリターンする。

Function: terminal-parameter terminal parameter: この関数は、terminalのパラメーターparameter(シンボル)の値をリターンする。terminalがparameterにたいするセッティングをもたない場合、この関数はnilをリターンする。

Function: set-terminal-parameter terminal parameter value: This function sets the parameter parameter of terminal to the specified value, and returns the previous value of that parameter.

以下は、特別な意味をもついくつかの端末パラメーターのリストです:

background-mode: 端末のバックグラウンドカラーの区分で、lightかdarkのいずれか。
normal-erase-is-backspace: 値は1か0で、これはその端末上でnormal-erase-is-backspace-modeがオンまたはオフのいずれに切り替えられたかに依存する。DEL Does Not Delete in The Emacs Manualを参照のこと。
terminal-initted: 端末の初期化後に、端末固有の初期化関数にセットされる。
tty-mode-set-strings: When present, a list of strings containing escape sequences that Emacs will output while configuring a tty for rendering. Emacs emits these strings only when configuring a terminal: if you want to enable a mode on a terminal that is already active (for example, while in tty-setup-hook), explicitly output the necessary escape sequence using send-string-to-terminal in addition to adding the sequence to tty-mode-set-strings.
tty-mode-reset-strings: When present, a list of strings that undo the effects of the strings in tty-mode-set-strings. Emacs emits these strings when exiting, deleting a terminal, or suspending itself.

29.6 フレームのタイトル

それぞれのフレームにはnameというパラメーターがあります。これは、ウィンドウシステムが通常フレーム上端に表示するフレームタイトルにたいする、デフォルトとしての役割をもちます。フレームプロパティnameをセットすることにより、明示的に名前を指定できます。

通常は名前を明示的に指定せず、Emacsが変数frame-title-formatに格納されたテンプレートにもとづき、自動的にフレーム名を計算します。Emacsはフレームが再表示されるたびに、毎回名前を再計算します。

Variable: frame-title-format: This variable specifies how to compute a name for a frame when you have not explicitly specified one. The variable’s value is actually a mode line construct, just like mode-line-format, except that the ‘%c’, ‘%C’, and ‘%l’ constructs are ignored. See section モードラインのデータ構造.

Variable: icon-title-format: この変数は、フレームタイトルを明示的に指定しないときの、アイコン化されたフレームの名前の計算方法を指定する。このタイトルはアイコン自体に表示される。

Variable: multiple-frames

この変数はEmacsにより自動的にセットされる。フレームが2つ以上(ミニバッファーのみのフレームと不可視のフレームは勘定に入らない)のとき、値はtとなる。frame-title-formatのデフォルト値は、フレームが複数存在する場合のみ、フレーム名にバッファー名を入れるために、multiple-framesを使用する。

この変数の値は、frame-title-formatとicon-title-formatの処理中を除き、正確である保証はない。

29.7 フレームの削除

生きたフレーム(live frame)とは、削除されていないフレームのことです。フレームが削除される際は、たとえそれへの参照元がなくなるまでLispオブジェクトとして存在し続けるとしても、端末ディスプレイからは削除されます。

Command: delete-frame &optional frame force

This function deletes the frame frame. The argument frame must specify a live frame (see below) and defaults to the selected frame.

It first deletes any child frame of frame (see section Child Frames) and any frame whose delete-before frame parameter (see section Frame Interaction Parameters) specifies frame. All such deletions are performed recursively; so this step makes sure that no other frames with frame as their ancestor will exist. Then, unless frame specifies a tooltip, this function runs the hook delete-frame-functions (each function getting one argument, frame) before actually killing the frame.

Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (see section ミニバッファーとフレーム). Normally, you cannot delete a frame if all other frames are invisible, but if force is non-nil, then you are allowed to do so.

Function: frame-live-p frame: This function returns non-nil if the frame frame has not been deleted. The possible non-nil return values are like those of framep. See section フレーム.

いくつかのウィンドウマネージャーは、ウィンドウを削除するコマンドを提供します。これらは、そのウィンドウを操作するプログラムに特別なメッセージを送ることにより機能します。Emacsがそれらメッセージのいずれかを受け取ったときは、delete-frameイベントを生成します。このイベントの通常の定義は、関数delete-frameを呼び出すコマンドです。その他のシステムイベントを参照してください。

Command: delete-other-frames &optional frame

This command deletes all frames on frame’s terminal, except frame. If frame uses another frame’s minibuffer, that minibuffer frame is left untouched. The argument frame must specify a live frame and defaults to the selected frame. Internally, this command works by calling delete-frame with force nil for all frames that shall be deleted.

This function does not delete any of frame’s child frames (see section Child Frames). If frame is a child frame, it deletes frame’s siblings only.

29.8 すべてのフレームを探す

Function: frame-list: この関数は、すべての生きたフレーム(削除されていないフレーム)のリストをリターンする。これはバッファーにたいするbuffer-listに類似しており、すべての端末上のフレームが含まれる。リターンされるリストは新たに作成されたものであり、このリストを変更してもEmacs内部への影響はない。

Function: visible-frame-list: This function returns a list of just the currently visible frames. See section フレームの可視性. Frames on text terminals always count as visible, even though only the selected one is actually displayed.

Function: frame-list-z-order &optional display

This function returns a list of Emacs’ frames, in Z (stacking) order (see section Raising, Lowering and Restacking Frames). The optional argument display specifies which display to poll. display should be either a frame or a display name (a string). If omitted or nil, that stands for the selected frame’s display. It returns nil if display contains no Emacs frame.

Frames are listed from topmost (first) to bottommost (last). As a special case, if display is non-nil and specifies a live frame, it returns the child frames of that frame in Z (stacking) order.

This function is not meaningful on text terminals.

Function: next-frame &optional frame minibuf

This function lets you cycle conveniently through all the frames on a specific terminal from an arbitrary starting point. It returns the frame following frame, in the list of all live frames, on frame’s terminal. The argument frame must specify a live frame and defaults to the selected frame. It never returns a frame whose no-other-frame parameter (see section Frame Interaction Parameters) is non-nil.

2つ目の引数minibufは、どのフレームを考慮するかを示す:

nil: ミニバッファーのみのフレームを除外。
visible: すべての可視フレームを考慮する。
0: すべての可視およびアイコン化されたフレームを考慮する。
ウィンドウ: 特定のウィンドウをミニバッファーとして使用するフレームだけを考慮する。
その他: すべてのフレームを考慮する。

Function: previous-frame &optional frame minibuf: next-frameと同様だが、すべてのフレームを逆方向に巡回する。

ウィンドウのサイクル順のnext-windowとprevious-windowも参照してください。

29.9 ミニバッファーとフレーム

Normally, each frame has its own minibuffer window at the bottom, which is used whenever that frame is selected. You can get that window with the function minibuffer-window (see section ミニバッファーのウィンドウ).

However, you can also create a frame without a minibuffer. Such a frame must use the minibuffer window of some other frame. That other frame will serve as surrogate minibuffer frame for this frame and cannot be deleted via delete-frame (see section フレームの削除) as long as this frame is live.

When you create the frame, you can explicitly specify its minibuffer window (in some other frame) with the minibuffer frame parameter (see section バッファーのパラメーター). If you don’t, then the minibuffer is found in the frame which is the value of the variable default-minibuffer-frame. Its value should be a frame that does have a minibuffer.

ミニバッファーのみのフレームを使用する場合は、ミニバッファーにエンター時にそのフレームを前面に移動(raise)したいと思うかもしれません。その場合は、変数minibuffer-auto-raiseにtをセットします。Raising, Lowering and Restacking Framesを参照してください。

Variable: default-minibuffer-frame: この変数は、デフォルトでミニバッファーウィンドウとして使用するフレームを指定する。これは、既存のフレームには影響しない。これはカレント端末にたいして常にローカルで、バッファーローカルにはできない。複数の端末を参照のこと。

29.10 入力のフォーカス

どんなときでも、Emacs内のただ1つのフレームが選択されたフレーム(selected frame)です。選択されたウィンドウは、常に選択されたフレーム上にあります。

When Emacs displays its frames on several terminals (see section 複数の端末), each terminal has its own selected frame. But only one of these is the selected frame: it’s the frame that belongs to the terminal from which the most recent input came. That is, when Emacs runs a command that came from a certain terminal, the selected frame is the one of that terminal. Since Emacs runs only a single command at any given time, it needs to consider only one selected frame at a time; this frame is what we call the selected frame in this manual. The display on which the selected frame is shown is the selected frame’s display.

Function: selected-frame: この関数は選択されたフレームをリターンする。

いくつかのウィンドウシステムおよびウィンドウマネージャーは、マウスがあるウィンドウオブジェクトにキーボード入力をダイレクトします。それ以外は、さまざまなウィンドウオブジェクトにフォーカスをシフト(shift the focus)するために、明示的なクリックやコマンドを要求します。どちらの方法でも、Emacsはフォーカスをもつフレームを自動的に追跡します。Lisp関数から別フレームに明示的に切り替えるためには、select-frame-set-input-focusを呼び出します。

Lisp programs can also switch frames temporarily by calling the function select-frame. This does not alter the window system’s concept of focus; rather, it escapes from the window manager’s control until that control is somehow reasserted.

テキスト端末使用時は、その端末上で一度に表示できるフレームは1つだけなので、select-frame呼び出し後、次回の再表示で新たに選択されたフレームが実際に表示されます。このフレームは、次のselect-frame呼び出しまで、選択されたままです。テキスト端末上の各フレームは、バッファー名の前に表示される番号をもちます(モードラインで使用される変数を参照)。

Function: select-frame-set-input-focus frame &optional norecord: この関数は、frameを選択、(他のフレームのせいで不明瞭な場合には)それを前面に移動(raise)して、Xサーバーのフォーカス授与を試みる。テキスト端末上では、次回再表示時に端末スクリーン全体に新たにフレームが表示される。オプション引数norecordは、select-frame(下記参照)のときと同じ意味をもつ。この関数のリターン値に意味はない。

Ideally, the function described next should focus a frame without also raising it above other frames. Unfortunately, many window-systems or window managers may refuse to comply.

Function: x-focus-frame frame &optional noactivate

This function gives frame the focus of the X server without necessarily raising it. frame nil means use the selected frame. Under X, the optional argument noactivate, if non-nil, means to avoid making frame’s window-system window the “active” window which should insist a bit more on avoiding to raise frame above other frames.

On MS-Windows the noactivate argument has no effect. However, if frame is a child frame (see section Child Frames), this function usually focuses frame without raising it above other child frames.

If there is no window system support, this function does nothing.

Command: select-frame frame &optional norecord

この関数は、フレームframeを選択し、Xサーバーのフォーカスがあればそれを一時的に無視する。frameにたいする選択は、次回ユーザーが別フレームに何かを行うか、この関数の次回呼び出しまで継続する(ウィンドウシステムを使用する場合は、以前に選択されていたフレームに依然としてウィンドウシステムの入力フォーカスがあるかもしれないので、コマンドループからリターン後に、そのフレームが選択されたフレームとしてリストアされるかもしれない)。

The specified frame becomes the selected frame, and its terminal becomes the selected terminal. This function then calls select-window as a subroutine, passing the window selected within frame as its first argument and norecord as its second argument (hence, if norecord is non-nil, this avoids changing the order of recently selected windows and the buffer list). See section ウィンドウの選択.

この関数はframe、またはframeが削除されていればnilをリターンする。

一般的には、実行後に端末を戻すよう切り替えることなく、別の端末に切り替えるのが可能な手段としてselect-frameを決して使用すべきではない。

Emacsは、サーバーおよびウィンドウマネージャーのリクエストとしてフレーム選択をアレンジすることにより、ウィンドウシステムと協調します。これは、適切なときにフォーカス(focus)と呼ばれる特殊な入力イベントを生成することにより行われます。コマンドループは、handle-switch-frameを呼び出してフォーカスイベントを処理します。フォーカスイベントを参照してください。

Command: handle-switch-frame frame

この関数は、フレームframe選択によりフォーカスイベントを処理する。

フォーカスイベントは通常、このコマンドを呼び出すことにより、その処理を行う。他の理由でこれを呼び出しではならない。

Function: redirect-frame-focus frame &optional focus-frame

この関数は、frameからfocus-frameにフォーカスをリダイレクトする。これは、frameにかわってfocus-frameが以降のキーストロークとイベントを受け取るであろうことを意味する。そのようなイベント後は、last-event-frameの値はfocus-frameになるだろう。また、frameを指定したswitch-frameイベントも、かわりに focus-frameを選択するだろう。

focus-frameが省略またはnilの場合は、frameにたいするすべての既存のリダイレクションがキャンセルされ、したがってframeが自身のイベントを再度受け取ることになる。

フォーカスリダイレクトの用途の1つは、ミニバッファーをもたないフレームにたいしてである。これらのフレームは、別フレーム上のミニバッファーを使用する。別フレーム上のミニバッファーをアクティブにすることは、そのフレームにフォーカスをリダイレクトすることである。これは、たとえマウスがミニバッファーをアクティブにしたフレーム内に留まっていても、ミニバッファーが属すフレームにフォーカスを置く。

フレーム選択は、フォーカスリダイレクションの変更も可能にする。fooが選択されているときにフレームbarを選択することにより、fooを指すすべてのリダイレクションは、かわりにbarを指す。これは、ユーザーがselect-windowを使用してあるフレームから別のフレームに切り替えた際に、フォーカスのリダイレクトが正しく機能することを可能にする。

これは、フォーカスが自身にリダイレクトされたフレームが、フォーカスがリダイレクトされていないフレームとは異なう扱いを受けることを意味する。前者にたいしてselect-frameは影響するが、後者には影響がない。

このリダイレクションは、それを変更するためにredirect-frame-focusが呼び出されるまで継続する。

Variable: focus-in-hook: This is a normal hook run when an Emacs frame gains input focus. The frame gaining focus is selected when this hook is run.

Variable: focus-out-hook: This is a normal hook run when an Emacs frame has lost input focus and no other Emacs frame has gained input focus instead.

User Option: focus-follows-mouse

This option informs Emacs whether and how the window manager transfers focus when you move the mouse pointer into a frame. It can have three meaningful values:

nil: The default value nil should be used when your window manager follows a “click-to-focus” policy where you have to click the mouse inside of a frame in order for that frame to gain focus.
t: The value t should be used when your window manager has the focus automatically follow the position of the mouse pointer but a frame that gains focus is not raised automatically and may even remain occluded by other window-system windows.
auto-raise: The value auto-raise should be used when your window manager has the focus automatically follow the position of the mouse pointer and a frame that gains focus is raised automatically.

If this option is non-nil, Emacs moves the mouse pointer to the frame selected by select-frame-set-input-focus. That function is used by a number of commands like, for example, other-frame and pop-to-buffer.

The distinction between the values t and auto-raise is not needed for “normal” frames because the window manager usually takes care of raising them. It is useful to automatically raise child frames via mouse-autoselect-window (see section Mouse Window Auto-selection).

Note that this option does not distinguish “sloppy” focus (where the frame that previously had focus retains focus as long as the mouse pointer does not move into another window manager window) from “strict” focus (where a frame immediately loses focus when it’s left by the mouse pointer). Neither does it recognize whether your window manager supports delayed focusing or auto-raising where you can explicitly specify the time until a new frame gets focus or is auto-raised.

You can supply a “focus follows mouse” policy for individual Emacs windows by customizing the variable mouse-autoselect-window (see section Mouse Window Auto-selection).

29.11 フレームの可視性

グラフィカルなディスプレイ上のフレームは可視(visible)、不可視(invisible)、またはアイコン化(iconified)されているかもしれません。可視なら、そのコンテンツは通常の方法により表示されます。アイコン化されている場合、そのコンテンツは表示されませんが、ビュー内にフレームを戻すための小さいアイコンがどこかにあります(いくつかのウィンドウマネージャーは、この状態をアイコン化ではなく最小化と呼ぶが、Emacsの見地ではこれらは同等である)。フレームが不可視なら、それはまったく表示されません。

The concept of visibility is strongly related to that of (un-)mapped frames. A frame (or, more precisely, its window-system window) is and becomes mapped when it is displayed for the first time and whenever it changes its state of visibility from iconified or invisible to visible. Conversely, a frame is and becomes unmapped whenever it changes its status from visible to iconified or invisible.

Visibility is meaningless on text terminals, since only the selected frame is actually displayed in any case.

Function: frame-visible-p frame

この関数は、フレームframeの可視性の状態をリターンする。値は、frameが可視ならt、不可視ならnil、アイコン化されている場合はiconになる。

On a text terminal, all frames are considered visible for the purposes of this function, even though only one frame is displayed. See section Raising, Lowering and Restacking Frames.

Command: iconify-frame &optional frame: This function iconifies frame frame. If you omit frame, it iconifies the selected frame. This usually makes all child frames of frame (and their descendants) invisible (see section Child Frames).

Command: make-frame-visible &optional frame

この関数は、フレームframeを可視にする。frameを省略した場合は、選択されたフレームを可視にする。これはフレームを前面に移動しないが、望むならraise-frameでそれを行うことができる(Raising, Lowering and Restacking Framesを参照)。

Making a frame visible usually makes all its child frames (and their descendants) visible as well (see section Child Frames).

Command: make-frame-invisible &optional frame force

This function makes frame frame invisible. If you omit frame, it makes the selected frame invisible. Usually, this makes all child frames of frame (and their descendants) invisible too (see section Child Frames).

Unless force is non-nil, this function refuses to make frame invisible if all other frames are invisible.

フレームの可視性の状態は、フレームパラメーターとしても利用可能である。つまりフレームパラメーターとして読み取りと変更ができる。ウィンドウ管理のパラメーターを参照のこと。ウィンドウマネージャーによりユーザーがフレームのアイコン化や非アイコン化を行うこともできる。これは、Emacsが何らかの制御を及ぼすのが可能なレベルより下のレベルにおいて発生するが、Emacsはそのような変化を追跡するために使用するイベントを提供する。その他のシステムイベントを参照のこと。

Function: x-double-buffered-p &optional frame: This function returns non-nil if frame is currently being rendered with double buffering. frame defaults to the selected frame.

29.12 Raising, Lowering and Restacking Frames

Most window systems use a desktop metaphor. Part of this metaphor is the idea that system-level windows (representing, e.g., Emacs frames) are stacked in a notional third dimension perpendicular to the screen surface. The order induced by stacking is total and usually referred to as stacking (or Z-) order. Where the areas of two windows overlap, the one higher up in that order will (partially) cover the one underneath.

You can raise a frame to the top of that order or lower a frame to its bottom by using the functions raise-frame and lower-frame. You can restack a frame directly above or below another frame using the function frame-restack.

Note that all functions described below will respect the adherence of frames (and all other window-system windows) to their respective z-group (see section 位置のパラメーター). For example, you usually cannot lower a frame below that of the desktop window and you cannot raise a frame whose z-group parameter is nil above the window-system’s taskbar or tooltip window.

Command: raise-frame &optional frame: This function raises frame frame (default, the selected frame) above all other frames belonging to the same or a lower z-group as frame. If frame is invisible or iconified, this makes it visible. If frame is a child frame (see section Child Frames), this raises frame above all other child frames of its parent.

Command: lower-frame &optional frame: This function lowers frame frame (default, the selected frame) below all other frames belonging to the same or a higher z-group as frame. If frame is a child frame (see section Child Frames), this lowers frame below all other child frames of its parent.

Function: frame-restack frame1 frame2 &optional above

This function restacks frame1 below frame2. This implies that if both frames are visible and their display areas overlap, frame2 will (partially) obscure frame1. If the optional third argument above is non-nil, this function restacks frame1 above frame2. This means that if both frames are visible and their display areas overlap, frame1 will (partially) obscure frame2.

Technically, this function may be thought of as an atomic action performed in two steps: The first step removes frame1’s window-system window from the display. The second step reinserts frame1’s window into the display below (above if above is true) that of frame2. Hence the position of frame2 in its display’s Z (stacking) order relative to all other frames excluding frame1 remains unaltered.

Some window managers may refuse to restack windows.

Note that the effect of restacking will only hold as long as neither of the involved frames is iconified or made invisible. You can use the z-group (see section 位置のパラメーター) frame parameter to add a frame to a group of frames permanently shown above or below other frames. As long as a frame belongs to one of these groups, restacking it will only affect its relative stacking position within that group. The effect of restacking frames belonging to different z-groups is undefined. You can list frames in their current stacking order with the function frame-list-z-order (see section すべてのフレームを探す).

User Option: minibuffer-auto-raise: これが非nilなら、ミニバッファーをアクティブにすることにより、ミニバッファーウィンドウのあるフレームが前面に移動される。

ウィンドウシステム上では、フレームパラメーターを使用して、(フレーム選択時に)auto-raising、(フレーム選択解除時に)auto-loweringを有効にできます。ウィンドウ管理のパラメーターを参照してください。

フレームを前面または背面に移動するという概念は、テキスト端末のフレームにも適用できます。各テキスト端末上で、一度に表示されるのは、常に最前面のフレームだけです。

Function: tty-top-frame &optional terminal: この関数は、terminal上の最前面のフレームをリターンする。terminalは端末オブジェクト、フレーム(そのフレームの端末を意味する)、またはnil(選択されたフレームの端末を意味する)であること。これがテキスト端末を参照しなければ、リターン値はnilとなる。

29.13 フレーム構成

フレーム構成(frame configuration)はフレームのカレント配置、すべてのプロパティ、および各ウィンドウのウィンドウ構成(ウィンドウの構成を参照)を記録します。

Function: current-frame-configuration: この関数は、フレームのカレント配置およびそのコンテンツを記述するフレーム構成のリストをリターンする。

Function: set-frame-configuration configuration &optional nodelete

この関数は、フレームの状態をconfigurationの記述にリストアする。しかし、この関数は削除されたフレームはリストアしない。

通常、この関数はconfiguration内にリストされない既存フレームすべてを削除する。しかしnodeleteが非nilなら、希望しないそれらフレームはかわりにアイコン化される。

29.14 Child Frames

Child frames are objects halfway between windows (see section ウィンドウ) and “normal” frames. Like windows, they are attached to an owning frame. Unlike windows, they may overlap each other—changing the size or position of one child frame does not change the size or position of any of its sibling child frames.

By design, operations to make or modify child frames are implemented with the help of frame parameters (see section フレームのパラメーター) without any specialized functions or customizable variables. Note that child frames are meaningful on graphical terminals only.

To create a new child frame or to convert a normal frame into a child frame, set that frame’s parent-frame parameter (see section Frame Interaction Parameters) to that of an already existing frame. The frame specified by that parameter will then be the frame’s parent frame as long as the parameter is not changed or reset. Technically, this makes the child frame’s window-system window a child window of the parent frame’s window-system window.

The parent-frame parameter can be changed at any time. Setting it to another frame reparents the child frame. Setting it to another child frame makes the frame a nested child frame. Setting it to nil restores the frame’s status as a top-level frame—a frame whose window-system window is a child of its display’s root window.

Since child frames can be arbitrarily nested, a frame can be both a child and a parent frame. Also, the relative roles of child and parent frame may be reversed at any time (though it’s usually a good idea to keep the size of a child frame sufficiently smaller than that of its parent). An error will be signaled for the attempt to make a frame an ancestor of itself.

Most window-systems clip a child frame at the native edges (see section Frame Geometry) of its parent frame—everything outside these edges is usually invisible. A child frame’s left and top parameters specify a position relative to the top-left corner of its parent’s native frame. When the parent frame is resized, this position remains conceptually unaltered.

NS builds do not clip child frames at the parent frame’s edges, allowing them to be positioned so they do not obscure the parent frame while still being visible themselves.

Usually, moving a parent frame moves along all its child frames and their descendants as well, keeping their relative positions unaltered. Note that the hook move-frame-functions (see section Frame Position) is run for a child frame only when the position of the child frame relative to its parent frame changes.

When a parent frame is resized, its child frames conceptually retain their previous sizes and their positions relative to the left upper corner of the parent. This means that a child frame may become (partially) invisible when its parent frame shrinks. The parameter keep-ratio (see section Frame Interaction Parameters) can be used to resize and reposition a child frame proportionally whenever its parent frame is resized. This may avoid obscuring parts of a frame when its parent frame is shrunk.

A visible child frame always appears on top of its parent frame thus obscuring parts of it, except on NS builds where it may be positioned beneath the parent. This is comparable to the window-system window of a top-level frame which also always appears on top of its parent window—the desktop’s root window. When a parent frame is iconified or made invisible (see section フレームの可視性), its child frames are made invisible. When a parent frame is deiconified or made visible, its child frames are made visible. When a parent frame is about to be deleted (see section フレームの削除), its child frames are recursively deleted before it.

Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menus bars for child frames. It seems advisable to disable both, menu and tool bars, via the frame’s initial parameters settings.

Usually, child frames do not exhibit window manager decorations like a title bar or external borders (see section Frame Geometry). When the child frame does not show a menu or tool bar, any other of the frame’s borders (see section レイアウトのパラメーター) can be used instead of the external borders.

In particular, under X (but not when building with GTK+), the frame’s outer border can be used. On MS-Windows, specifying a non-zero outer border width will show a one-pixel wide external border. Under all window-systems, the internal border can be used. In either case, it’s advisable to disable a child frame’s window manager decorations with the undecorated frame parameter (see section ウィンドウ管理のパラメーター).

To resize or move an undecorated child frame with the mouse, special frame parameters (see section Mouse Dragging Parameters) have to be used. The internal border of a child frame, if present, can be used to resize the frame with the mouse, provided that frame has a non-nil drag-internal-border parameter. If set, the snap-width parameter indicates the number of pixels where the frame snaps at the respective edge or corner of its parent frame.

There are two ways to drag an entire child frame with the mouse: The drag-with-mode-line parameter, if non-nil, allows to drag a frame without minibuffer window (see section ミニバッファーのウィンドウ) via the mode line area of its bottommost window. The drag-with-header-line parameter, if non-nil, allows to drag the frame via the header line area of its topmost window.

In order to give a child frame a draggable header or mode line, the window parameters mode-line-format and header-line-format are handy (see section ウィンドウのパラメーター). These allow to remove an unwanted mode line (when drag-with-header-line is chosen) and to remove mouse-sensitive areas which might interfere with frame dragging.

To avoid that dragging moves a frame completely out of its parent’s native frame, something which might happen when the mouse cursor overshoots and makes the frame difficult to retrieve once the mouse button has been released, it is advisable to set the frame’s top-visible or bottom-visible parameter correspondingly.

The top-visible parameter specifies the number of pixels at the top of the frame that always remain visible within the parent’s native frame during dragging and should be set when specifying a non-nil drag-with-header-line parameter. The bottom-visible parameter specifies the number of pixels at the bottom of the frame that always remain visible within the parent’s native frame during dragging and should be preferred when specifying a non-nil drag-with-mode-line parameter.

When a child frame is used for displaying a buffer via display-buffer-in-child-frame (see section display-bufferにたいするアクション関数), the frame’s auto-hide-function parameter (see section Frame Interaction Parameters) can be set to a function, in order to appropriately deal with the frame when the window displaying the buffer shall be quit.

When a child frame is used during minibuffer interaction, for example, to display completions in a separate window, the minibuffer-exit parameter (see section Frame Interaction Parameters) is useful in order to deal with the frame when the minibuffer is exited.

The behavior of child frames deviates from that of top-level frames in a number of other ways as well. Here we sketch a few of them:

The semantics of maximizing and iconifying child frames is highly window-system dependent. As a rule, applications should never invoke these operations on child frames. By default, invoking iconify-frame on a child frame will try to iconify the top-level frame corresponding to that child frame instead. To obtain a different behavior, users may customize the option iconify-child-frame described below.
Raising, lowering and restacking child frames (see section Raising, Lowering and Restacking Frames) or changing the z-group (see section 位置のパラメーター) of a child frame changes only the stacking order of child frames with the same parent.
Many window-systems are not able to change the opacity (see section フォントとカラーのパラメーター) of child frames.
Transferring focus from a child frame to an ancestor that is not its parent by clicking with the mouse in a visible part of that ancestor’s window may fail with some window-systems. You may have to click into the direct parent’s window-system window first.
Window managers might not bother to extend their focus follows mouse policy to child frames. Customizing mouse-autoselect-window can help in this regard (see section Mouse Window Auto-selection).
Dropping (see section ドラッグアンドドロップ) on child frames is not guaranteed to work on all window-systems. Some will drop the object on the parent frame or on some ancestor instead.

The following two functions can be useful when working with child and parent frames:

Function: frame-parent &optional frame

This function returns the parent frame of frame. The parent frame of frame is the Emacs frame whose window-system window is the parent window of frame’s window-system window. If such a frame exists, frame is considered a child frame of that frame.

This function returns nil if frame has no parent frame.

Function: frame-ancestor-p ancestor descendant: This functions returns non-nil if ancestor is an ancestor of descendant. ancestor is an ancestor of descendant when it is either descendant’s parent frame or it is an ancestor of descendant’s parent frame. Both, ancestor and descendant must specify live frames.

Note also the function window-largest-empty-rectangle (see section 座標とウィンドウ) which can be used to inscribe a child frame in the largest empty area of an existing window. This can be useful to avoid that a child frame obscures any text shown in that window.

Customizing the following option can be useful to tweak the behavior of iconify-frame for child frames.

User Option: iconify-child-frame

This option tells Emacs how to proceed when it is asked to iconify a child frame. If it is nil, iconify-frame will do nothing when invoked on a child frame. If it is iconify-top-level, Emacs will try to iconify the top-level frame that is the ancestor of this child frame instead. If it is make-invisible, Emacs will try to make this child frame invisible instead of iconifying it.

Any other value means to try iconifying the child frame. Since such an attempt may not be honored by all window managers and can even lead to making the child frame unresponsive to user actions, the default is to iconify the top level frame instead.

29.15 マウスの追跡

マウスをトラック(track: 追跡)するのが有用なことが時折あります。マウスのトラックとは、マウスの位置を示す何かを表示して、マウス移動とともにそのインジケーターを移動する、という意味です。効果的にマウスをトラックするためには、マウスが実際に移動するまで待機する手段が必要になります。

マウスをトラックする便利なのは、マウスのモーション(motion: 移動)を表すイベントを問い合わせる方法です。その後は、そのイベントを待機することにより、モーションを待機できます。加えて、発生し得る他の類のイベントも、簡単に処理できます。ボタンのリリースのような何か他のイベントだけを待機してマウスを永久にトラックするは通常は望ましくないので、これは有用です。

Special Form: track-mouse body…

このスペシャルフォームは、マウスモーションイベントの生成を有効にして、bodyを実行する。通常、bodyはモーションイベントを読み取るためにread-eventを使用し、それに対応して表示を変更する。マウスモーションイベントのフォーマットについては、モーションイベントを参照のこと。

track-mouseの値は、body内の最後のフォームの値である。ボタンのリリースを示すup-event、またはトラックを止めるべきタイミングを意味する類のイベントを確認した際にはリターンするよう、bodyをデザインするべきである。

The track-mouse form causes Emacs to generate mouse motion events by binding the variable track-mouse to a non-nil value. If that variable has the special value dragging, it additionally instructs the display engine to refrain from changing the shape of the mouse pointer. This is desirable in Lisp programs that require mouse dragging across large portions of Emacs display, which might otherwise cause the mouse pointer to change its shape according to the display portion it hovers on (see section ポインターの形状). Therefore, Lisp programs that need the mouse pointer to retain its original shape during dragging should bind track-mouse to the value dragging at the beginning of their body.

マウスモーションをトラックする通常の目的は、それ以降に発生するボタンのプッシュやリリースをカレント位置に示すことです。

多くの場合は、テキストプロパティmouse-face(特殊な意味をもつプロパティを参照)を使用することにより、マウスをトラックする必要性を回避できます。これは、より低レベルで機能し、かつLispレベルのマウストラッキングよりスムーズに実行されます。

29.16 マウスの位置

関数mouse-positionおよびset-mouse-positionは、マウスのカレント位置にたいするアクセスを提供します。

Function: mouse-position: This function returns a description of the position of the mouse. The value looks like (frame x . y), where x and y are integers giving the (possibly rounded) position in multiples of the default character size of frame (see section Frame Font) relative to the native position of frame (see section Frame Geometry).

Variable: mouse-position-function

非nilなら、この変数の値はmouse-positionにたいして呼び出される関数である。mouse-positionはリターン直前には、自身の通常のリターン値を唯一の引数としてこの関数を呼び出し、それが何であれその関数がリターンしたものをリターンする。

このアブノーマルフックは、xt-mouse.elのようにLispレベルでマウス処理を行う必要があるパッケージのために存在する。

Function: set-mouse-position frame x y

This function warps the mouse to position x, y in frame frame. The arguments x and y are integers, giving the position in multiples of the default character size of frame (see section Frame Font) relative to the native position of frame (see section Frame Geometry).

The resulting mouse position is constrained to the native frame of frame. If frame is not visible, this function does nothing. The return value is not significant.

Function: mouse-pixel-position: この関数はmouse-positionと似ているが、文字単位ではなくピクセル単位の座標をリターンする。

Function: set-mouse-pixel-position frame x y

This function warps the mouse like set-mouse-position except that x and y are in units of pixels rather than units of characters.

The resulting mouse position is not constrained to the native frame of frame. If frame is not visible, this function does nothing. The return value is not significant.

On a graphical terminal the following two functions allow the absolute position of the mouse cursor to be retrieved and set.

Function: mouse-absolute-pixel-position: This function returns a cons cell (x . y) of the coordinates of the mouse cursor position in pixels, relative to a position (0, 0) of the selected frame’s display.

Function: set-mouse-absolute-pixel-position x y: This function moves the mouse cursor to the position (x, y). The coordinates x and y are interpreted in pixels relative to a position (0, 0) of the selected frame’s display.

The following function can tell whether the mouse cursor is currently visible on a frame:

Function: frame-pointer-visible-p &optional frame: This predicate function returns non-nil if the mouse pointer displayed on frame is visible; otherwise it returns nil. frame omitted or nil means the selected frame. This is useful when make-pointer-invisible is set to t: it allows you to know if the pointer has been hidden. See Mouse Avoidance in The Emacs Manual.

29.17 ポップアップメニュー

Lispプログラムはポップアップメニューを表示できるので、ユーザーはマウスで候補を選択できます。テキスト端末上では、マウスが利用不可なら、キーボードのモーションキーC-n、C-p、上矢印キー、下矢印キーで候補を選択できます。

Function: x-popup-menu position menu

この関数は、ポップアップメニューを表示して、ユーザーが何を選択したかの指標をリターンする。

引数positionは、メニュー左上隅をスクリーン上どこに置くか指定する。これはマウスボタンイベント(ユーザーがボタンを操作した位置にメニューを置くよう告げる)、または以下の形式のリストのいずれかである:

((xoffset yoffset) window)

ここで、xoffsetとyoffsetはwindow左上隅からピクセル単位で測られた座標である。windowはウィンドウ、またはフレームかもしれない。

positionがtの場合、それはマウスのカレント位置の使用を意味する(テキスト端末上でマウスが利用不可ならフレーム左上隅)。positionがnilなら、それは実際にメニューをポップアップせずに、menu内で指定されたキーマップと等価なキーバインディングを事前に計算することを意味する。

引数menuは、メニュー内で何を表示するかを告げる。これはキーマップまたはキーマップのリストを指定できる(メニューキーアップを参照)。この場合、リターン値はユーザー選択に対応するイベントのリストである。選択がサブメニュー内で発生した場合、このリストには複数の要素がある(x-popup-menuはそのイベントシーケンスにバインドされたコマンドを実際には実行しないことに注意)。テキスト端末、およびメニュータイトルをサポートするツールキットでは、menuがキーマップならタイトルはmenuのプロンプト文字列、menuがキーマップのリストなら最初のキーマップのプロンプト文字列から取得される(メニューの定義を参照)。

かわりに、menuは以下の形式をもつこともできる:

(title pane1 pane2...)

ここで、それぞれのpaneは以下の形式のリストである

(title item1 item2...)

それぞれitemは、コンスセル(line . value)であること。ここでlineは文字列、valueはlineが選択された場合にリターンされる値である。メニューキーマップと異なり、nilのvalueは選択不可のメニューアイテムを作成しない。かわりに、それぞれのitemにコンスセルではなく文字列を指定できる。これは選択不可のメニューアイテムを作成する。

たとえば有効な選択からマウスを外してクリックしたり、C-gをタイプすることにより、有効な選択を行うことなくユーザーがメニューを取り除いた場合は、通常はquitしてx-popup-menuはリターンしない。しかし、positionがマウスボタンイベント(ユーザーがマウスでメニューを呼び出したことを示す)なら、quitは起こらずx-popup-menuはリターンする。

使用上の注意: メニューキーマップで定義したプレフィクスキー処理を行えるなら、メニューの表示にx-popup-menuを使用しないでください。メニューの実装にメニューキーマップを使用する場合は、C-h cおよびC-h aでメニュー内の個別アイテムの確認、およびそれらにたいするヘルプを提供できます。かわりにx-popup-menuを呼び出すコマンドを定義することによりメニューを実装した場合、ヘルプ機能はそのコマンド内部で何が起こっているか知ることができず、そのメニューアイテムのヘルプを何も与えられません。

マウス移動によりサブメニュー間を切り替えるメニューバーのメカニズムは、それがx-popup-menuを呼び出すか確認するために、コマンドの定義を見ることができません。したがって、x-popup-menuを使用してサブメニューの実装を試みた場合、それは統合された方式でメニューバーとともに機能しません。メニューバーのすべてのサブメニューは、親メニューのメニューキーマップにより実装され、決してx-popup-menuで実装されないのは、これが理由です。メニューバー Barを参照してください。

メニューバーのサブメニューのコンテンツを変化させたい場合にも、その実装には依然としてメニューキーマップを使用するべきです。コンテンツを変化させるためには、必要に応じてメニューキーマップのコンテンツを更新するために、フック関数をmenu-bar-update-hookに追加してください。

29.18 ダイアログボックス

ダイアログボックスとはポップアップメニューの一種です。外見は多少異なり、常にフレーム中央に表示され、階層を1つしかもたず1つ以上のボタンがあります。ユーザーが“yes”、“no”、および別の少数の候補で応答ができる質問を尋ねるのが、ダイアログボックスの主な用途です。単一のボタンでは、ユーザーに重要な情報の確認を強いることもできます。関数y-or-n-pおよびyes-or-no-pは、マウスのクリックにより呼び出されたコマンドから呼び出された際は、キーボードのかわりにダイアログボックスを使用します。

Function: x-popup-dialog position contents &optional header

この関数は、ポップアップダイアログボックスを表示して、ユーザーが何を選択したかの指標をリターンする。引数contentsは、提供するための候補を指定する。これは、以下のフォーマットをもつ:

(title (string . value)…)

これは、x-popup-menuにたいして単一paneを指定するリストのように見える。

リターン値は、選択された候補のvalueである。

x-popup-menuの場合と同様、このリストの要素はコンスセル(string . value)のかわりに、単なる文字列かもしれない。これは、選択不可のボックスを作成する。

このリスト内にnilがある場合、それは左手側と右手側のアイテムを分ける。つまり、nilより前のアイテムは左、nilより後のアイテムは右に表示される。リスト内にnilを含めない場合は、およそ半数づつが両サイドに表示される。

ダイアログボックスは、常にフレームの中央に表示される。引数positionは、どのフレームかを指定する。可能な値はx-popup-menuの場合と同様だが、正確な座標や個別のウィンドウは問題ではなく、フレームだけが問題となる。

headerが非nilならボックスのフレームタイトルは‘Information’、それ以外は‘Question’になる。前者はmessage-box(see message-boxを参照)にたいして使用される(テキスト端末上ではボックスタイトルは表示されない)。

いくつかの構成では、Emacsは本当のダイアログボックスを表示できないので、かわりにフレーム中央のポップアップメニュー内に同じアイテムを表示する。

たとえばウィンドウマネージャーを使用して、有効な選択を行うことなくユーザーがダイアログボックスを取り除いた場合は、通常はquitしてx-popup-dialogはリターンしない。

29.19 ポインターの形状

テキストプロパティpointerや、イメージならイメージプロパティ:pointerおよび:mapを使用して、特定のテキストやイメージにたいしてマウスポインターのスタイルを指定できます。これらのプロパティに使用できる値はtext(またはnil)、arrow、hand、vdrag、hdrag、modeline、hourglassです。textは、テキスト上で使用される、通常のマウスポインタースタイルを意味します。

ウィンドウの空部分(void parts: バッファーコンテンツのどの部分にも対応しない部分)の上では、マウスポインターは通常arrowスタイルを使用しますが、void-text-area-pointerをセットすることにより、異なるスタイルを指定できます。

User Option: void-text-area-pointer: この変数は、空テキストエリアにたいするマウスポインタースタイルを指定する。このエリアには、行末の後や、バッファー終端行の下が含まれる。デフォルトでは、arrow(non-text)ポインタースタイルを使用。

Xを使用する際は、変数x-pointer-shapeをセットすることにより、textの本当の外見を指定できます。

Variable: x-pointer-shape: この変数は、Emacsフレーム内でtextポインタースタイルに通常使用するポインターシェイプを指定する。

Variable: x-sensitive-text-pointer-shape: この変数は、マウスがマウスセンシティブテキスト上にあるときのポインターシェイプを指定する。

これらの変数は、新たに作成されるフレームに影響します。通常これらは既存のフレームに効果はありませんが、フレームのマウスカラーのインストール時には、これら2つ変数のカレント値もインストールされます。フォントとカラーのパラメーターを参照してください。

これらのポインターシェイプのいずれかを指定するために使用可能な値は、ファイルlisp/term/x-win.el内で定義されています。それらのリストを確認するには、M-x apropos RET x-pointer RETを使用してください。

29.20 ウィンドウシステムによる選択

In window systems, such as X, data can be transferred between different applications by means of selections. X defines an arbitrary number of selection types, each of which can store its own data; however, only three are commonly used: the clipboard, primary selection, and secondary selection. Other window systems support only the clipboard. See Cut and Paste in The GNU Emacs Manual, for Emacs commands that make use of these selections. This section documents the low-level functions for reading and setting window-system selections.

Command: gui-set-selection type data

This function sets a window-system selection. It takes two arguments: a selection type type, and the value to assign to it, data.

typeはシンボルであること。通常はPRIMARY、SECONDARY、CLIPBOARDのいずれかである。これらは、Xウィンドウシステムの慣例に対応する大文字のシンボル名である。typeがnilなら、それはPRIMARYを意味する。

dataがnilなら、それはその選択をクリアーすることを意味する。それ以外では、dataは文字列、シンボル、整数(2つの整数からなるコンスかリスト)、オーバーレイ、同じバッファーを指す2つのマーカーのコンスを指定できる。オーバーレイとマーカーのペアは、そのオーバーレイまたはマーカー間のテキストを意味する。引数dataには、非ベクターの選択の値のベクターも指定できる。

この関数はdataをリターンする。

Function: gui-get-selection &optional type data-type

This function accesses selections set up by Emacs or by other programs. It takes two optional arguments, type and data-type. The default for type, the selection type, is PRIMARY.

The data-type argument specifies the form of data conversion to use, to convert the raw data obtained from another program into Lisp data. Meaningful values include TEXT, STRING, UTF8_STRING, TARGETS, LENGTH, DELETE, FILE_NAME, CHARACTER_POSITION, NAME, LINE_NUMBER, COLUMN_NUMBER, OWNER_OS, HOST_NAME, USER, CLASS, ATOM, and INTEGER. (These are symbols with upper-case names in accord with X conventions.) The default for data-type is STRING. Window systems other than X usually support only a small subset of these types, in addition to STRING.

User Option: selection-coding-system: この変数は、選択やクリップボードに読み書きする際のコーディングシステムを指定する。コーディングシステムを参照してください。デフォルトはcompound-text-with-extensionsで、これはX11が通常使用するテキスト表現に変換する。

When Emacs runs on MS-Windows, it does not implement X selections in general, but it does support the clipboard. gui-get-selection and gui-set-selection on MS-Windows support the text data type only; if the clipboard holds other types of data, Emacs treats the clipboard as empty. The supported data type is STRING.

For backward compatibility, there are obsolete aliases x-get-selection and x-set-selection, which were the names of gui-get-selection and gui-set-selection before Emacs 25.1.

29.21 ドラッグアンドドロップ

ユーザーが別のアプリケーションからEmacsに何かをドラッグをした際、その別アプリケーションはEmacsがドラッグされたデータを処理可能か告げることを期待します。変数x-dnd-test-functionは、何を応答するか決定するために、Emacsにより使用されます。デフォルト値はx-dnd-default-test-functionで、これはドロップされたデータのタイプがx-dnd-known-types内にあれば、ドロップを受け入れます。何か別の条件にもとづいてEmacsにドロップを許容または拒絶させたい場合は、x-dnd-test-functionおよび/またはx-dnd-known-typesをカスタマイズできます。

Emacsが異なるタイプのドロップを処理する方法を変更したり、新たなタイプを追加したい場合は、x-dnd-types-alistをカスタマイズします。これには、他のアプリケーションがドラッグアンドドロップに使用するのが何のタイプなのか、詳細な知識が要求されます。

EmacsにURLがドロップされたとき、それはファイルかもしれませんが、他のURLタイプ(ftp、http、...)であるかもしれません。Emacsはまず、そのURLに何を行うべきか判断するために、dnd-protocol-alistをチェックします。それにマッチがなく、かつbrowse-url-browser-functionがalistなら、Emacsはそこでマッチを探します。それでもマッチが見つからなければ、そのURLにたいするテキストを挿入します。これらの変数をカスタマイズすれば、Emacsの挙動を変更できます。

29.22 カラー名

カラー名(color name)とは、カラーを指定するテキスト(通常は文字列)です。‘black’、‘white’、‘red’等が指定できます。定義された名前のリストは、M-x list-colors-displayを使用して確認できます。‘#rgb’や‘RGB:r/g/b’のような、数値的な形式でカラーを指定することもできます。ここで、rは赤(red)、gは緑(green)、bは青(blue)のレベルを指定します。1桁、2桁、3桁、または4桁の16進数をrに使用できます。その後、gとbには同じ桁数の16進数を同様に使用しなければなりません。これにより、総桁数が3､6､9､または12桁の16進数となります(カラーの数値的なRGB指定についての詳細は、Xウィンドウシステムのドキュメントを参照されたい)。

以下の関数は、有効なカラー名と、それらの外見を判断する手段を提供します。以下で説明するように、その値は選択されたフレーム(selected frame)に依存する場合があります。“選択されたフレーム”という用語の意味については、入力のフォーカスを参照してください。

補完付きでカラー名のユーザー入力を読み取るには、read-colorを使用します(read-colorを参照)。

Function: color-defined-p color &optional frame

この関数は、カラー名が有意かどうかを報告する。もし有意ならt、それ以外はnilをリターンする。引数frameは、どのフレームのディスプレイにたいして問い合わせるかを指定する。frameが省略またはnilの場合は、選択されたフレームが使用される。

これは、使用しているディスプレイがそのカラーをサポートするかどうかは告げないことに注意。X使用時には、すべての種類のディスプレイ上のすべての定義されたカラーを問い合わせることができ、何らかの結果(通常は可能な限り近いカラー)を得ることができるでしょう。あるフレームが特定のカラーを実際に表示できるかどうか判断するためには、color-supported-p(以下参照)を使用してください。

この関数は、以前はx-color-defined-pと呼ばれており、その名前は今でもエイリアスとしてサポートされている。

Function: defined-colors &optional frame

この関数は、frame(デフォルトは選択されたフレーム)上で定義かつサポートされるカラー名のリストをリターンする。frameがカラーをサポートしなければ、値はnilとなる。

この関数は、以前はx-defined-colorsと呼ばれており、その名前は今でもエイリアスとしてサポートされている。

Function: color-supported-p color &optional frame background-p

これは、frameが実際にカラーcolor(または最低でもそれに近いカラー)を表示可能ならtをリターンする。frameが省略またはnilなら、この問いは選択されたフレームに適用される。

フォアグラウンドおよびバックグラウンドにたいして異なるカラーセットをサポートする端末がいくつかある。background-pが非nilの場合、それはcolorがバックグラウンドとして、それ以外はフォアグラウンドとして使用可能かどうかを問うことを意味する。

引数colorは、有効なカラー名でなければならない。

Function: color-gray-p color &optional frame: これは、colorがframeのディスプレイ上の定義として、グレイスケールならtをリターンする。frameが省略またはnilなら、この問いは選択されたフレームに適用される。colorが有効なカラー名でなければ、この関数はnilをリターンする。

Function: color-values color &optional frame

この関数は、frame上で理想的にはcolorがどのように見えるべきかを記述する値をリターンする。colorが定義済みの場合、値は赤、緑、青の割合を与える3つの整数からなるリストである。それぞれの整数の範囲は原則として0から65535だが、この範囲全体を使用しないディスプレイもいくつか存在するだろう。この3要素のリストは、カラーのRGB値(rgb values)と呼ばれる。

colorが未定義なら、値はnilである。

(color-values "black")
     ⇒ (0 0 0)
(color-values "white")
     ⇒ (65280 65280 65280)
(color-values "red")
     ⇒ (65280 0 0)
(color-values "pink")
     ⇒ (65280 49152 51968)
(color-values "hungry")
     ⇒ nil

カラーの値は、frameのディスプレイにたいしてリターンされる。frameが省略またはnilの場合、この情報は選択されたフレームのディスプレイにたいしてリターンされる。このフレームがカラーを表示できない場合、値はnilとなる。

この関数は、以前はx-color-valuesと呼ばれており、その名前は今でもエイリアスとしてサポートされている。

29.23 テキスト端末のカラー

通常、テキスト端末は少しのカラーしかサポートせず、コンピューターはカラー選択に小さい整数を使用します。これは、選択したカラーがどのように見えるかコンピューターが信頼性をもって告げることができず、どのカラーがどのような小さい整数に対応するかという情報を、をアプリケーションに伝える必要があることを意味します。しかし、Emacsは標準的なカラーセットを知っており、それらの自動的な使用を試みるでしょう。

このセクションで説明する関数は、Emacsが端末カラーを使用する方法を制御します。

これらの関数のうちのいくつかは、カラー名で説明したRGB値(rgb values)を使用またはリターンします。

これらの関数は、オプション引数としてディスプレイ(フレームまたは端末名のいずれか)を受け取ります。わたしたちは将来、異なる端末上で異なるカラーをEmacsにサポートさせたいと望んでいます。そうすれば、この引数はどの端末を処理するか(デフォルトは選択されたフレームの端末。入力のフォーカスを参照のこと)を指定するようになるでしょう。しかし現在のところ、frame引数に効果はありません。

Function: tty-color-define name number &optional rgb frame

この関数は、カラー名nameを、その端末上のカラー値numberに関連付ける。

オプション引数rgbが指定された場合、それはそのカラーが実際にどのように見えるかを指定する、3つの数値のリストからなるRGB値である。rgbを指定しない場合、Emacsはそれがどのように見えるか知らないので、そのカラーを他のカラーに近似するためにtty-color-approximateで使用することができない。

Function: tty-color-clear &optional frame: この関数は、テキスト端末の定義済みカラーのテーブルをクリアーする。

Function: tty-color-alist &optional frame

この関数は、テキスト端末がサポートする既知のカラーを記録したalistをリターンする。

それぞれの要素は、(name number . rgb)または(name number)という形式をもつ。ここで、nameはカラー名、numberはその端末でカラー指定に使用される数値である。rgbが与えられた場合、それはそのカラーが実際にどのように見えるかを告げる3つのカラー値(赤、緑、青)のリストである。

Function: tty-color-approximate rgb &optional frame: この関数は、displayにたいしてサポートされた既知のカラーの中から、RGB値rgb(カラー値のリスト)で記述されたもっとも近いカラーを探す。リターン値は、tty-color-alistの要素である。

Function: tty-color-translate color &optional frame: この関数は、displayにたいしてサポートされた既知のカラーの中から、もっとも近いカラーのインデックス(整数)をリターンする。名前colorが未定義なら、値はnilとなる。

29.24 Xリソース

このセクションでは、Xリソース、または他のオペレーティングシステム上での等価物を問い合わせたり使用する関数および変数をいくつか説明します。Xリソースにたいする詳細な情報は、X Resources in The GNU Emacs Manualを参照してください。

Function: x-get-resource attribute class &optional component subclass

関数x-get-resourceは、Xウィンドウのデフォルトデータベースからリソース値を取得する。

リソースは、キー(key)とクラス(class)の組み合わせによりインデックス付けされている。この関数は、‘instance.attribute’という形式をキー(instanceはEmacsが呼び出されたときの名前)、クラスとして‘Emacs.class’として使用することにより検索を行う。

オプション引数componentおよびsubclassは、それぞれキーおよびクラスを追加する。指定する場合は両方を指定するか、さもなくばどちらも指定してはならない。これらを指定した場合、キーは‘instance.component.attribute’、クラスは‘Emacs.class.subclass’となる。

Variable: x-resource-class: This variable specifies the application name that x-get-resource should look up. The default value is "Emacs". You can examine X resources for other application names by binding this variable to some other string, around a call to x-get-resource.

Variable: x-resource-name: この変数は、x-get-resourceが照会すべきインスタンス名を指定する。デフォルト値はEmacs呼び出し時の名前、またはスイッチ‘-name’または‘-rn’で指定された値である。

上述のいくつかを説明するために、Xリソースファイル(通常は~/.Xdefaultsや~/.Xresources)内に以下のような行があるとしましょう:

xterm.vt100.background: yellow

その場合は:

(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "vt100.background" "VT100.Background"))
     ⇒ "yellow"

(let ((x-resource-class "XTerm") (x-resource-name "xterm"))
  (x-get-resource "background" "VT100" "vt100" "Background"))
     ⇒ "yellow"

Variable: inhibit-x-resources: この変数が非nilなら、EmacsはXリソースを照会せず、新たなフレーム作成時にXリソースは何も効果をもたない。

29.25 ディスプレー機能のテスト

このセクションの関数は、特定のディスプレイの基本的な能力を説明します。Lispプログラムは、そのディスプレイが行えることに挙動を合わせるために、それらを使用できます。たとえば、ポップアップメニューがサポートされなければ、通常はポップアップメニューを使用するプログラムは、ミニバッファーを使用できます。

これらの関数のオプション引数displayは、問い合わせるディスプレイを指定します。これにはディスプレイ名、フレーム(フレームがあるディスプレイを指定)、またはnil(選択されたフレームのディスプレイを参照する。入力のフォーカスを参照されたい)を指定できます。

ディスプレイに関する情報を取得するその他の関数については、カラー名を参照してください。

Function: display-popup-menus-p &optional display: この関数は、display上でポップアップメニューがサポートされていればt、それ以外はnilをリターンする。Emacsディスプレイのある部分をマウスでクリックすることによりメニューがポップアップするので、ポップアップメニューのサポートにはマウスが利用可能であることが要求される。

Function: display-graphic-p &optional display: この関数は、displayが一度に複フレームおよび複数の異なるフォントを表示する能力を有すグラフィックディスプレイならtをリターンする。これは、Xのようなウィンドウシステムのディスプレイにたいしては真、テキスト端末にたいしては偽となる。

Function: display-mouse-p &optional display: この関数は、displayでマウスが利用可能ならt、それ以外はnilをリターンする。

Function: display-color-p &optional display: この関数は、そのスクリーンがカラースクリーンならtをリターンする。これは以前はx-display-color-pと呼ばれており、その名前はエイリアスとして今でもサポートされる。

Function: display-grayscale-p &optional display: この関数は、スクリーンがグレースケールを表示可能ならtをリターンする(カラーディスプレイはすべてこれを行うことができる)。

Function: display-supports-face-attributes-p attributes &optional display

この関数は、attributes内のすべてのフェイス属性がサポートされていれば非nilをリターンする(フェイスの属性を参照)。

The definition of “supported” is somewhat heuristic, but basically means that a face containing all the attributes in attributes, when merged with the default face for display, can be represented in a way that’s

デフォルトフェイスとは異なる外見で表示でき、かつ
close in spirit to what the attributes specify, if not exact.

Point (2) implies that a :weight black attribute will be satisfied by any display that can display bold, as will :foreground "yellow" as long as some yellowish color can be displayed, but :slant italic will not be satisfied by the tty display code’s automatic substitution of a dim face for italic.

Function: display-selections-p &optional display: この関数は、displayが選択(selections)をサポートすればtをリターンする。ウィンドウ化されたディスプレイでは、通常は選択がサポートされるが、他の場合にもサポートされ得る。

Function: display-images-p &optional display: この関数は、displayがイメージを表示可能ならtをリターンする。ウィンドウ化されたディスプレイは原則イメージを処理するが、イメージにたいするサポートを欠くシステムもいくつかある。イメージをサポートしないディスプレイ上では、Emacsはツールバーを表示できない。

Function: display-screens &optional display: この関数は、そのディスプレイに割り当てられたスクリーンの数をリターンする。

Function: display-pixel-height &optional display

この関数は、スクリーンの高さをピクセルでリターンする。文字端末では、文字数で高さを与える。

For graphical terminals, note that on multi-monitor setups this refers to the pixel height for all physical monitors associated with display. See section 複数の端末.

Function: display-pixel-width &optional display

この関数は、スクリーンの幅をピクセルでリターンする。文字端末では、文字数で幅を与える。

For graphical terminals, note that on multi-monitor setups this refers to the pixel width for all physical monitors associated with display. See section 複数の端末.

Function: display-mm-height &optional display

この関数は、スクリーンの高さをミリメートルでリターンする。nilなら、Emacsがその情報を取得できなかったことを意味する。

For graphical terminals, note that on multi-monitor setups this refers to the height for all physical monitors associated with display. See section 複数の端末.

Function: display-mm-width &optional display

この関数は、スクリーンの幅をミリメートルでリターンする。nilなら、Emacsがその情報を取得できなかったことを意味する。

For graphical terminals, note that on multi-monitor setups this refers to the width for all physical monitors associated with display. See section 複数の端末.

User Option: display-mm-dimensions-alist: この変数は、システムの提供する値が不正な場合にdisplay-mm-heightおよびdisplay-mm-widthがリターンするグラフィカルなディスプレイのサイズを、ユーザーが指定できるようにする。

Function: display-backing-store &optional display

この関数は、そのディスプレイのバッキングストアー(backing store)の能力をリターンする。バッキングストアーとは、非露出ウィンドウ(およびウィンドウの一部)のピクセルを記録しておいて、露出時に素早く表示できるようにすることを意味する。

値にはシンボルalways、when-mapped、not-usefulである。特定の種類のディスプレイにたいしてこの問いが適用外の際、この関数はnilをリターンすることもある。

Function: display-save-under &optional display: この関数は、そのディスプレイがSaveUnder機能をサポートすれば非nilをリターンする。この機能は、ポップアップウィンドウに隠されるピクセルを保存して、素早くポップダウンができるようにするために使用される。

Function: display-planes &optional display: この関数は、そのディスプレイがサポートする平面数(number of planes)をリターンする。これは通常、ピクセルごとのビット(bits per pixel: 色深度[bpp])数である。ttyディスプレイでは、サポートされるカラー数の2進対数(log to base two)である。

Function: display-visual-class &optional display: この関数は、そのスクリーンのビジュアルクラスをリターンする。値はシンボルstatic-gray(カラー数変更不可の限定されたグレイ)、gray-scale(フルレンジのグレイ)、static-color(カラー数変更不可の限定されたカラー)、pseudo-color(限定されたカラー数のカラー)、true-color(フルレンジのカラー)、およびdirect-color(フルレンジのカラー)のいずれかである。

Function: display-color-cells &optional display: この関数は、そのスクリーンがサポートするカラーのセル数をリターンする。

以下の関数は、Emacsが指定されたdisplayを表示する場所に使用されるウィンドウシステムの追加情報を取得します(関数名先頭のx-は歴史的理由による)。

Function: x-server-version &optional display: この関数は、GNUおよびUnixシステム上のXサーバーのような、display上で実行されているGUIウィンドウシステムのバージョン番号のリストをリターンする。値は3つの整数からなるリストで、1つ目と2つ目の整数はそのプロトコルのメジャーバージョン番号とマイナーバージョン番号、3つ目の整数はウィンドウシステムソフトウェア自体のディストリビューター固有のリリース番号である。GNUおよびUnixシステムでは、通常これらはXプロトコルのバージョン番号と、Xサーバーソフトウェアのディストリビューター固有のリリース番号である。MS-Windowsでは、WidowsのOSバージョン番号である。

Function: x-server-vendor &optional display

This function returns the vendor that provided the window system software (as a string). On GNU and Unix systems this really means whoever distributes the X server. On MS-Windows this is the vendor ID string of the Windows OS (Microsoft).

X開発者がソフトウェア配布者を“vendors”とラベル付けしたことは、いかなるシステムも非商業的に開発および配布できないと彼らが誤って仮定したことを示している。

30 ポジション

位置(position)とは、バッファーのテキストの文字のインデックスです。より正確には、位置とは2つの文字間(または最初の文字の前、または最後の文字の後)の箇所を識別し、与えられた位置の前あるいは後の文字のように表現することができます。しかし、“ある位置にある文字”のように表現することもあり、その場合はその位置の後の文字を意味します。

Positions are usually represented as integers starting from 1, but can also be represented as markers—special objects that relocate automatically when text is inserted or deleted so they stay with the surrounding characters. Functions that expect an argument to be a position (an integer), but accept a marker as a substitute, normally ignore which buffer the marker points into; they convert the marker to an integer, and use that integer, exactly as if you had passed the integer as the argument, even if the marker points to the wrong buffer. A marker that points nowhere cannot convert to an integer; using it instead of an integer causes an error. See section マーカー.

See also the field feature (see section フィールドの定義と使用), which provides functions that are used by many cursor-motion commands.

30.1 ポイント

ポイント(point)とは、多くの編集コマンドにより使用される、バッファーの特別な位置のことです。これらのコマンドには、自己挿入型のタイプ文字やテキスト挿入関数が含まれます。その他のコマンドは、別の箇所でテキストの編集や挿入ができるようにポイントを移動します。

他の位置と同様、ポイントは特定の文字ではなく、2つの文字の間(または最初の文字の前、または最後の文字の後)を指します。通常、端末ではポイント直後の文字の上にカーソルを表示します。つまり、ポイントは実際はカーソルのある文字の前にあります。

ポイントの値は1より小さくなることはなく、そのバッファーのサイズに1を加えた値より大きくなることはありません。ナローイング(ナローイングを参照)が効力をもつ場合、ポイントはそのバッファーのアクセス可能な範囲内(範囲の境界はバッファーの先頭か終端のいずれかの可能性がある)に閉じ込められます。

バッファーはそれぞれ自身のポイント値をもち、それは他のバッファーのポイント値とは無関係です。ウィンドウもそれぞれポイント値をもち、他のウィンドウ内の同じバッファー上のポイント値とは無関係です。同じバッファーを表示する種々のウィンドウが異なるポイント値をもてるのは、これが理由です。あるバッファーがただ1つのウィンドウに表示されているときは、そのバッファーのポイントとそのウィンドウのポイントは、通常は同じ値をもち、区別が重要になるのは稀です。詳細はウィンドウとポイントを参照してください。

Function: point

この関数は、カレントバッファー内のポイントの値を、整数でリターンする。

(point)
     ⇒ 175

Function: point-min: この関数は、カレントバッファー内のアクセス可能なポイントの最小値をリターンする。これは通常は1だが、ナローイングが効力をもつ場合は、ナローイングしたリージョンの開始位置となる(ナローイングを参照)。

Function: point-max: この関数は、カレントバッファー内のアクセス可能なポイントの最大値をリターンする。これはナローイングされていなければは(1+ (buffer-size))だが、ナローイングが効力をもつ場合は、ナローイングしたリージョンの終端位置となる(ナローイングを参照)。

Function: buffer-end flag: この関数は、flagが0より大なら(point-max)、それ以外は(point-min)をリターンする。引数flagは数値でなければならない。

Function: buffer-size &optional buffer

この関数は、カレントバッファー内の文字数のトータルをリターンする。ナローイング(ナローイングを参照)されていなければ、point-maxはこれに1を加えた値をリターンする。

bufferにバッファーを指定した場合、値はbufferのサイズになる。

(buffer-size)
     ⇒ 35

(point-max)
     ⇒ 36

30.2 モーション

モーション関数は、ポイントのカレント値、バッファーの先頭または終端、または選択されたウィンドウ端のいずれかより、相対的にポイントの値を変更します。ポイントを参照してください。

30.2.1 文字単位の移動		文字単位での移動。
30.2.2 単語単位の移動		単語単位での移動。
30.2.3 バッファー終端への移動		バッファー先頭または終端への移動。
30.2.4 テキスト行単位の移動		テキスト行単位での移動。
30.2.5 スクリーン行単位の移動		表示される行単位での移動。
30.2.6 バランスのとれたカッコを越えた移動		リストやS式の解析による移動。
30.2.7 文字のスキップ		特定の集合に属す文字のスキップ。

30.2.1 文字単位の移動

以下の関数は、文字数にもとづいてポイントを移動します。 goto-charは基本的なプリミティブで、その他の関数はこれを使用しています。

Command: goto-char position

この関数は、カレントバッファー内のポイントの値をpositionにセットする。

ナローイングが効力をもつ場合でも、positionは依然としてバッファー先頭から数えられるが、ポイントをアクセス可能な範囲外に移動することはできない。positionが範囲外の場合、goto-charはアクセス可能な範囲の先頭または終端にポイントを移動する。

この関数がインタラクティブに呼び出された際は、positionの値は数プレフィクス引数、プレフィクス引数が与えられなかった場合はミニバッファーから値を読み取る。

goto-charはpositionをリターンする。

Command: forward-char &optional count

この関数は前方、すなわちバッファーの終端方向にポイントをcount文字移動する(countが負なら後方、すなわちバッファーの先頭方向にポイントを移動する)。countがnilの場合のデフォルトは1。

バッファー(ナローイングが効力をもつ場合はアクセス可能な範囲の境界)の先頭または終端を超えて移動を試みた場合はエラーシンボルbeginning-of-bufferまたはend-of-bufferのエラーをシグナルする。

インタラクティブな呼び出しでは、数プレフィクス引数がcountとなる。

Command: backward-char &optional count: 移動方向が逆であることを除き、これはforward-charと同様である。

30.2.2 単語単位の移動

The functions for parsing words described below use the syntax table and char-script-table to decide whether a given character is part of a word. See section 構文テーブル, and see 文字のプロパティ.

Command: forward-word &optional count

This function moves point forward count words (or backward if count is negative). If count is omitted or nil, it defaults to 1. In an interactive call, count is specified by the numeric prefix argument.

“Moving one word” means moving until point crosses a word-constituent character, which indicates the beginning of a word, and then continue moving until the word ends. By default, characters that begin and end words, known as word boundaries, are defined by the current buffer’s syntax table (see section 構文クラスのテーブル), but modes can override that by setting up a suitable find-word-boundary-function-table, described below. Characters that belong to different scripts (as defined by char-script-table), also define a word boundary (see section 文字のプロパティ). In any case, this function cannot move point past the boundary of the accessible portion of the buffer, or across a field boundary (see section フィールドの定義と使用). The most common case of a field boundary is the end of the prompt in the minibuffer.

バッファー境界またはフィールド境界により途中で停止することなく単語count個分の移動が可能なら、値はtとなる。それ以外ではリターン値はnilで、ポイントはバッファー境界またはフィールド境界で停止する。

inhibit-field-text-motionが非nilなら、この関数はフィールド境界を無視する。

Command: backward-word &optional count: この関数は、単語の前に遭遇するまで、前方ではなく後方に移動することを除き、forward-wordと同様である。

User Option: words-include-escapes: This variable affects the behavior of forward-word and backward-word, and everything that uses them. If it is non-nil, then characters in the escape and character-quote syntax classes count as part of words. Otherwise, they do not.

Variable: inhibit-field-text-motion: この変数が非nilならforward-word、forward-sentence、forward-paragraphを含む特定のモーション関数は、フィールド境界を無視する。

Variable: find-word-boundary-function-table: This variable affects the behavior of forward-word and backward-word, and everything that uses them. Its value is a char-table (see section 文字テーブル) of functions to search for word boundaries. If a character has a non-nil entry in this table, then when a word starts or ends with that character, the corresponding function will be called with 2 arguments: pos and limit. The function should return the position of the other word boundary. Specifically, if pos is smaller than limit, then pos is at the beginning of a word, and the function should return the position after the last character of the word; otherwise, pos is at the last character of a word, and the function should return the position of that word’s first character.

Function: forward-word-strictly &optional count: This function is like forward-word, but it is not affected by find-word-boundary-function-table. Lisp programs that should not change behavior when word movement is modified by modes which set that table, such as subword-mode, should use this function instead of forward-word.

Function: backward-word-strictly &optional count: This function is like backward-word, but it is not affected by find-word-boundary-function-table. Like with forward-word-strictly, use this function instead of backward-word when movement by words should only consider syntax tables.

30.2.3 バッファー終端への移動

バッファーの先頭にポイントを移動するには、以下のように記述します:

(goto-char (point-min))

同様に、バッファーの終端に移動するには、以下を使用します:

(goto-char (point-max))

以下の2つは、ユーザーがこれらを行うためのコマンドです。これらはマークをセットしてメッセージをエコーエリアに表示するため、Lispプログラム内で使用しないよう警告するために、ここに記述します。

Command: beginning-of-buffer &optional n

この関数は、バッファー(ナローイングが効力をもつ場合はアクセス可能範囲の境界)の先頭にポイントを移動して、以前の位置にマークをセットする(Transient Markモードの場合、マークがすでにアクティブならマークはセットしない)。

nが非nilなら、バッファーのアクセス可能範囲の先頭から10分のnの位置にポイントを置く。インタラクティブな呼び出しでは、nは数プレフィクス引数が与えられればその値、それ以外でのデフォルトはnilである。

警告: この関数をLispプログラム内で使用してはならない。

Command: end-of-buffer &optional n

この関数は、バッファー(ナローイングが効力をもつ場合はアクセス可能範囲の境界)の終端にポイントを移動して、以前の位置にマークをセットする(Transient Markモードの場合、マークがすでにアクティブならマークはセットしない)。nが非nilなら、バッファーのアクセス可能範囲の終端から10分のnの位置にポイントを置く。

インタラクティブな呼び出しでは、nは数プレフィクス引数が与えられればその値、それ以外でのデフォルトはnilである。<

警告: この関数をLispプログラム内で使用してはならない。

30.2.4 テキスト行単位の移動

テキスト行とは、改行で区切られたバッファーの範囲です。改行は前の行の一部とみなされます。最初のテキスト行はバッファー先頭で始まり、最後のテキスト行は最後の文字が改行かどうかは関係なくバッファー終端で終わります。バッファーからテキスト行への分割は、そのウィンドウの幅、表示の行継続、タブおよびその他の制御文字の表示方法に影響されません。

Command: beginning-of-line &optional count

この関数は、カレント行の先頭にポイントを移動する。引数countが非nilまたは1以外なら、前方にcount-1行移動してから、その行の先頭に移動する。

この関数は、別の行に移動する場合を除き、フィールド境界(フィールドの定義と使用を参照)を超えてポイントを移動しない。したがって、countがnilまたは1で、かつポイントがフィールド境界で開始される場合は、ポイントを移動しない。フィールド境界を無視させるには、inhibit-field-text-motionをtにバインドするか、かわりにforward-line関数を使用する。たとえば、フィールド境界を無視することを除けば、(forward-line 0)は(beginning-of-line)と同じことを行う。

この関数がバッファー(ナローイングが効力をもつ場合はアクセス可能範囲)の終端に到達した場合は、ポイントをその位置に置く。エラーはシグナルされない。

Function: line-beginning-position &optional count: (beginning-of-line count)が移動するであろう位置をリターンする。

Command: end-of-line &optional count

この関数は、カレント行の終端にポイントを移動する。引数countが非nilまたは1以外なら、前方にcount-1行移動してから、その行の終端に移動する。

Function: line-end-position &optional count: (end-of-line count)が移動するであろう位置をリターンする。

Command: forward-line &optional count

This function moves point forward count lines, to the beginning of the line following that. If count is negative, it moves point -count lines backward, to the beginning of a line preceding that. If count is zero, it moves point to the beginning of the current line. If count is nil, that means 1.

forward-lineが指定された行数を移動する前にバッファー(またはアクセス可能範囲)の先頭か終端に遭遇した場合は、そこにポイントをセットする。エラーはシグナルされない。

forward-line returns the difference between count and the number of lines actually moved. If you attempt to move down five lines from the beginning of a buffer that has only three lines, point stops at the end of the last line, and the value will be 2. As an explicit exception, if the last accessible line is non-empty, but has no newline (e.g., if the buffer ends without a newline), the function sets point to the end of that line, and the value returned by the function counts that line as one line successfully moved.

インタラクティブな呼び出しでは、数プレフィクス引数がcountとなる。

Function: count-lines start end: この関数は、カレントバッファー内の位置startとendの間の行数をリターンする。startとendが等しければ、リターン値は0になる。それ以外は、たとえstartとendが同一行にあっても、最小でも1をリターンする。これらの間にあるテキストは、それだけを孤立して考えたると、それが空でない限りは最小でも1行を含まなければならないからである。

Command: count-words start end

この関数は、カレントバッファー内の位置startとendの間にある単語の数をリターンする。

この関数は、インタラクティブに呼び出すこともできる。その場合はバッファー、またはリージョンがアクティブならリージョン内の行数、単語数、文字数を報告するメッセージをプリントする。

Function: line-number-at-pos &optional pos absolute: This function returns the line number in the current buffer corresponding to the buffer position pos. If pos is nil or omitted, the current buffer position is used. If absolute is nil, the default, counting starts at (point-min), so the value refers to the contents of the accessible portion of the (potentially narrowed) buffer. If absolute is non-nil, ignore any narrowing and return the absolute line number.

ポイント周辺のテキストを調べるの関数bolpとeolpも参照してください。これらの関数はポイントを移動しませんが、ポイントがすでに行頭または行末にあるかどうかをテストします。

30.2.5 スクリーン行単位の移動

前のセクションの行関数は、改行文字で区切られたテキスト行だけを数えました。対照的に、以下の関数はスクリーン行を数えます。スクリーン行は、スクリーン上でテキストが表示される方法にしたがって定義されます。あるテキスト行1行が、選択されたウィンドウの幅にフィット可能な程に十分短ければ、それはスクリーン行で1行になりますが、それ以外は複数のスクリーン行になり得ます。

テキスト行が追加スクリーン行に継続されずに、そのスクリーンで切り詰められる(truncated)場合があります。そのような場合は、vertical-motionでforward-lineのようにポイントを移動します。切り詰めを参照してください。

文字列が与えられた場合、その幅は、文字の外見を制御するフラグに依存するため、与えられたテキスト断片にたいして、たとえそれが選択されたウィンドウ上でさえも(幅、切り詰め有無、ディスプレイテーブルはウィンドウごとに異なり得るので)、そのテキストがあるバッファーに応じて、vertical-motionの挙動は異なります。通常の表示の慣習を参照してください。

以下の関数は、スクリーン行のブレーク位置を判断するためにテキストをスキャンするため、スキャンする長さに比例して時間を要します。

Function: vertical-motion count &optional window cur-col

この関数は、ポイントのあるスクリーン行からスクリーン行でcount行下に移動して、そのスクリーン行の先頭にポイントを移動する。countが負なら、かわりに上に移動する。

count引数には、整数のかわりにコンスセル(cols . lines)を指定できる。その場合、関数はスクリーン行でlines行移動して、そのスクリーン行の視覚的な行頭(visual start)からcols列目にポイントを置く。colsは、その行の視覚的(visual)な開始から数えられることに注意。そのウィンドウが水平スクロール(水平スクロールを参照)されている場合には、ポイントが置かれる列は、スクロールされたテキストの列数が加えられるだろう。

リターン値は、ポイントが移動したスクリーン行の行数である。バッファーの先頭か終端に到達していたら、この値は絶対値ではcountより小になるかもしれない。

ウィンドウwindow引数幅、水平スクロール、ディスプレイテーブルのようなパラメーターの取得に使用される。しかしvertical-motionは、たとえwindowがカレントで他のバッファーを表示していたとしても常に、カレントバッファーにたいして処理を行う。

The optional argument cur-col specifies the current column when the function is called. This is the window-relative horizontal coordinate of point, measured in units of font width of the frame’s default face. Providing it speeds up the function, especially in very long lines, because the function doesn’t have to go back in the buffer in order to determine the current column. Note that cur-col is also counted from the visual start of the line.

Function: count-screen-lines &optional beg end count-final-newline window

この関数は、begからendのテキスト内のスクリーン行の行数をリターンする。スクリーン行数は行継続やディスプレイテーブル等により、実際の行数とは異なるかもしれない。begおよびendがnil、または省略された場合のデフォルトは、そのバッファーのアクセス可能範囲の先頭と終端である。

そのリージョンが改行で終わる場合、オプションの第3引数count-final-newlineがnilなら、それは無視される。

オプションの第4引数windowは、幅や水平スクロール等のパラメーターを取得するウィンドウを指定する。デフォルトは、選択されたウィンドウのパラメーターを使用する。

vertical-motionと同様、count-screen-linesはwindow内にどのバッファーが表示されていようと、常にカレントバッファーを使用する。これにより、バッファーが何らかのウィンドウにカレントで表示されているか否かにかかわらず、任意にバッファーにたいしてcount-screen-linesの使用が可能になる。

Command: move-to-window-line count

This function moves point with respect to the text currently displayed in the selected window. It moves point to the beginning of the screen line count screen lines from the top of the window; zero means the topmost line. If count is negative, that specifies a position -count lines from the bottom (or the last line of the buffer, if the buffer ends above the specified screen position); thus, count of -1 specifies the last fully visible screen line of the window.

countがnilの場合、ポイントはウィンドウ中央の行の先頭に移動する。countの絶対値がウィンドウサイズより大なら、ウィンドウが十分に高かったならそのスクリーン行は表示されていたであろう位置に、ポイントを移動する。これは、おそらく次回の再表示の際に、その箇所がスクリーン上になるようなスクロールを発生させるだろう。

インタラクティブな呼び出しでは、数プレフィクス引数がcountとなる。

The value returned is the screen line number point has moved to, relative to the top line of the window.

Function: move-to-window-group-line count: This function is like move-to-window-line, except that when the selected window is a part of a group of windows (see Window Group), move-to-window-group-line will move to a position with respect to the entire group, not just the single window. This condition holds when the buffer local variable move-to-window-group-line-function is set to a function. In this case, move-to-window-group-line calls the function with the argument count, then returns its result.

Function: compute-motion from frompos to topos width offsets window

この関数は、カレントバッファーをスキャンして、スクリーン位置を計算する。これは位置fromがスクリーン座標fromposにあると仮定して、そこから位置toまたは座標toposのいずれか先に到達したほうまで、バッファーを前方にスキャンする。これはスキャン終了のバッファー位置と、スクリーン座標をリターンする。

座標引数fromposおよびtoposは、(hpos . vpos)という形式のコンスセルである。

引数widthは、テキストを表示するために利用可能な列数である。これは、継続行の処理に影響する。nilは、そのウィンドウ内で使用可能な実際のテキスト列数で、(window-width window)がリターンする値と等しい。

引数offsetsはnil、または(hscroll . tab-offset)という形式のコンスセルのいずれかである。ここでhscrollは、左マージンのために表示されない列数であり、呼び出し側のほとんどはwindow-hscrollを呼び出すことにより、これを取得する。一方tab-offsetは、スクリーン上の列数と、バッファー内の列数の間のオフセットである。これは継続行において、前のスクリーン行の幅がtab-widthの整数倍でないときは、非0になる可能性がある。非継続行では、これは常に0である。

ウィンドウwindowの役割は、使用するディスプレイテーブルの指定することだけである。compute-motionは、window内に表示されているのがどのバッファーであろうと、カレントバッファーを処理する。

リターン値は、5つの要素をもつリストである:

(pos hpos vpos prevhpos contin)

ここで、posはスキャンが停止したバッファー位置、vposは垂直スクリーン位置、hposは水平スクリーン位置である。

結果prevhposは、posから1文字戻った水平位置である。結果continは、最後の行が前の文字の後(または中)から継続されていれば、tとなる。

たとえば、あるウィンドウのスクリーン行lineの列colのバッファー位置を求めるには、そのウィンドウのdisplay-start(表示開始)位置をfrom、そのウィンドウの左上隅の座標をfromposとして渡す。スキャンをそのバッファーのアクセス可能範囲の終端に制限するために、バッファーの(point-max)をtoに、lineとcolをtoposに渡す。以下は、これを行う関数である:

(defun coordinates-of-position (col line)
  (car (compute-motion (window-start)
                       '(0 . 0)
                       (point-max)
                       (cons col line)
                       (window-width)
                       (cons (window-hscroll) 0)
                       (selected-window))))

ミニバッファーにたいしてcompute-motionを使う際は、最初のスクリーン行の先頭の水平位置を取得するために、minibuffer-prompt-widthを使用する必要がある。

30.2.6 バランスのとれたカッコを越えた移動

以下は、バランスの取れたカッコ式(balanced-parenthesis。これらの式を横断して移動することと関連して、Emacsではsexp(S式)とも呼ばれる)と関連する、いくつかの関数です。これらの関数がさまざまな文字を処理する方法は、構文テーブル(syntax table)が制御します。構文テーブルを参照してください。sexp、またはその一部にたいする低レベルのプリミティブについては、式のパースを参照してください。ユーザーレベルのコマンドについては、Commands for Editing with Parentheses in The GNU Emacs Manualを参照してください。

Command: forward-list &optional arg: この関数は、バランスの取れたカッコのグループを、arg(デフォルトは1)グループ前方に移動する(単語やクォート文字のペアーでクォートされた文字列は無視される)。

Command: backward-list &optional arg: この関数は、バランスの取れたカッコのグループを、arg(デフォルトは1)グループ後方に移動する(単語やクォート文字のペアーでクォートされた文字列は無視される)。

Command: up-list &optional arg escape-strings no-syntax-crossing: This function moves forward out of arg (default 1) levels of parentheses. A negative argument means move backward but still to a less deep spot. If escape-strings is non-nil (as it is interactively), move out of enclosing strings as well. If no-syntax-crossing is non-nil (as it is interactively), prefer to break out of any enclosing string instead of moving to the start of a list broken across multiple strings. On error, location of point is unspecified.

Command: backward-up-list &optional arg escape-strings no-syntax-crossing: This function is just like up-list, but with a negated argument.

Command: down-list &optional arg: この関数は、カッコをarg(デフォルトは1)レベル内側前方に移動する。負の引数では後方に移動するが、同様に深いレベル(-argレベル)に移動する。

Command: forward-sexp &optional arg

この関数は、バランスの取れた式(balanced expressions)を、arg(デフォルトは1)前方に移動する。バランスの取れた式にはカッコ等で区切られた式、および単語や文字列定数のようなものも含まれる。式のパースを参照のこと。たとえば、

---------- Buffer: foo ----------
(concat∗ "foo " (car x) y z)
---------- Buffer: foo ----------

(forward-sexp 3)
     ⇒ nil

---------- Buffer: foo ----------
(concat "foo " (car x) y∗ z)
---------- Buffer: foo ----------

Command: backward-sexp &optional arg: この関数は、バランスの取れた式(balanced expressions)を、arg(デフォルトは1)後方に移動する。

Command: beginning-of-defun &optional arg: この関数は、後方にarg番目のdefunの先頭に移動する。argが負なら、実際には前方に移動するが、defunの終端ではなく先頭に移動することは変わらない。argのデフォルトは1。

Command: end-of-defun &optional arg: この関数は、前方にarg番目のdefunの終端に移動する。argが負なら、実際には後方に移動するが、defunの先頭ではなく終端に移動することは変わらない。argのデフォルトは1。

User Option: defun-prompt-regexp: 非nilなら、このバッファーローカル変数はdefunの始まりとなる開きカッコの前に出現し得るテキストを指定する正規表現を保持する。つまりd、この正規表現にたいするマッチで始まり、その後に開きカッコ構文(open-parenthesis syntax)が続くのがdefunである。

User Option: open-paren-in-column-0-is-defun-start: この変数の値が非nilなら、列0にある開きカッコはdefunの始まりとみなされる。nilの場合、列0の開きカッコは特別な意味をもたない。デフォルトはt。

Variable: beginning-of-defun-function: 非nilなら、この変数はdefunの開始を見つける関数を保持する。関数beginning-of-defunは、通常の手法を使うかわりに、その関数に自身のオプション引数を渡して、その関数を呼び出す。その引数が非nilなら、その関数はその回数分の関数呼び出しにより、beginning-of-defunが行うように後方に移動すること。

Variable: end-of-defun-function: 非nilなら、この変数はdefunの終端を見つける関数を保持する。関数end-of-defunは、通常の手法を使うかわりに、その関数を呼び出す。

30.2.7 文字のスキップ

以下の2つの関数は、指定された文字セットを超えてポイントを移動します。これらの関数は、たとえば空白文字をスキップするためによく使用されます。関連する関数については、モーションと構文を参照してください。

これらの関数は検索関数(検索とマッチングを参照)が行うように、そのバッファーがマルチバイト(multibyte)ならマルチバイトに、ユニバイト(unibyte)ならユニバイトに、そのセットト文字列を変換します。

Function: skip-chars-forward character-set &optional limit

この関数は、与えられた文字セットをスキップして、カレントバッファー内のポイント前方に移動する。これはポイントの後の文字を調べて、その文字がcharacter-setにマッチすればポイントを進める。そして、マッチしない文字に到達するまで、これを継続する。この関数は、超えて移動した文字数をリターンする。

引数character-setが、正規表現での‘[…]’内部と同様だが、‘]’で終端されず、‘\’が‘^’、‘-’、‘\’をクォートする点が異なる。つまり、"a-zA-Z"はすべての英字をスキップして最初の非英字の前で停止し、"^a-zA-Z"はすべての非英字をスキップして最初の英字の前で停止する。正規表現を参照のこと。"[:alnum:]"のような文字クラスも使用できる。see section 文字クラスを参照されたい。

limit(数字かマーカー)が与えられた場合、それはポイントがスキップして到達できる、そのバッファー内の最大位置を指定する。ポイントはlimit、またはlimitの前でストップするだろう。

以下の例では、ポイントは最初‘T’の直前に置かれている。フォーム評価後、ポイントはその行の末尾(‘hat’の‘t’と改行の間)に置かれる。この関数は、すべての英字とスペースをスキップするが、改行はスキップしない。

---------- Buffer: foo ----------
I read "∗The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(skip-chars-forward "a-zA-Z ")
     ⇒ 18

---------- Buffer: foo ----------
I read "The cat in the hat∗
comes back" twice.
---------- Buffer: foo ----------

Function: skip-chars-backward character-set &optional limit

この関数は、limitに至るまでcharacter-setにマッチする文字をスキップして、ポイントを後方に移動する。これはskip-chars-forwardと同様だが、ポイントを移動する方向が異なる。

リターン値は、移動した距離を示す。これは、0以上の整数である。

30.3 エクスカーション

It is often useful to move point temporarily within a localized portion of the program. This is called an excursion, and it is done with the save-excursion special form. This construct remembers the initial identity of the current buffer, and its value of point, and restores them after the excursion completes. It is the standard way to move point within one part of a program and avoid affecting the rest of the program, and is used thousands of times in the Lisp sources of Emacs.

カレントバッファー自体のみの保存およびリストアが必要な場合は、かわりにsave-current-bufferやwith-current-bufferを使用してください(カレントバッファーを参照)。ウィンドウ構成の保存やリストアが必要なら、ウィンドウの構成およびフレーム構成で説明されているフォームを参照してください。

Special Form: save-excursion body…

This special form saves the identity of the current buffer and the value of point in it, evaluates body, and finally restores the buffer and its saved value of point. Both saved values are restored even in case of an abnormal exit via throw or error (see section 非ローカル脱出).

save-excursionがリターンする値はbody内の最後のフォームの結果、またはbodyフォームが与えられなければnilをリターンする。

Because save-excursion only saves point for the buffer that was current at the start of the excursion, any changes made to point in other buffers, during the excursion, will remain in effect afterward. This frequently leads to unintended consequences, so the byte compiler warns if you call set-buffer during an excursion:

Warning: Use ‘with-current-buffer’ rather than
         save-excursion+set-buffer

このような問題を避けるには、以下の例のように望むカレントバッファーをセット後にのみsave-excursionを呼び出すべきです:

(defun append-string-to-buffer (string buffer)
  "BUFFER末尾にSTRINGを追加"
  (with-current-buffer buffer
    (save-excursion
      (goto-char (point-max))
      (insert string))))

同じように、save-excursionはswitch-to-bufferのような関数が変更したウィンドウ/バッファーの対応をリストアしません。

警告: 保存されたポイント値に隣接する通常のテキスト挿入は、それがすべてのマーカーを再配置するのと同様、保存されたポイントカーを再配置します。より正確には、保存される値は挿入タイプnilのマーカーです。Marker 挿入タイプを参照してください。したがって、保存されたポイント値のリストア時は、通常は挿入されたテキストの直前になります。

Macro: save-mark-and-excursion body…: This macro is like save-excursion, but also saves and restores the mark location and mark-active. This macro does what save-excursion did before Emacs 25.1.

30.4 ナローイング

ナローイング(narrowing)とは、Emacs編集コマンドがアドレス指定可能なテキストを、あるバッファー内の制限された文字範囲に限定することを意味します。アドレス可能なテキストは、そのバッファーのアクセス可能範囲(accessible portion)と呼ばれます。

ナローイングは2つのバッファー位置により指定され、それがアクセス可能範囲の開始と終了になります。ほとんどの編集コマンドおよびプリミティブにたいし、これらの位置はそれぞれそのバッファーの先頭と終端に置き換えられます。ナローイングが効果をもつ間、アクセス可能範囲外のテキストは表示されず、その外部にポイントを移動することはできません。ナローイングは実際のバッファー位置(ポイントを参照)を変更しないことに注意してください。ほとんどの関数は、アクセス可能範囲外のテキストにたいする操作を受け付けません。

バッファーを保存するコマンドは、ナローイングの影響を受けません。どんなナローイングであろうと、それらはバッファー全体を保存します。

単一バッファー内に、タイプが大きく異なるテキストを複数表示する必要がある場合は、2つのバッファー間でのテキストの交換で説明する代替機能の使用を考慮してみてください。

Command: narrow-to-region start end

この関数は、アクセス可能範囲の開始と終了に、カレントバッファーのstartとendをセットする。どちらの引数も、文字位置で指定すること。

インタラクティブな呼び出しでは、startとendはカレントリージョン(ポイントとマークで、小さいほうが前者)にセットされる。

Command: narrow-to-page &optional move-count

この関数は、カレントページだけを含むように、カレントバッファーのアクセス可能範囲をセットする。1つ目のオプション引数move-countが非nilの場合は、move-countで前方または後方へ移動後に、1ページにナローすることを意味する。変数page-delimiterは、ページの開始と終了の位置を指定する(編集で使用される標準的な正規表現を参照)。

インタラクティブな呼び出しでは、move-countには数プレフィクス引数がセットされる。

Command: widen

この関数は、カレントバッファーにたいするすべてのナローイングをキャンセルする。これはワイドニング(widening)と呼ばれる。これは、以下の式と等価である:

(narrow-to-region 1 (1+ (buffer-size)))

Function: buffer-narrowed-p: この関数は、そのバッファーがナローされていれば非nil、それ以外はnilをリターンする。

Special Form: save-restriction body…

このスペシャルフォームは、アクセス可能範囲のカレントのバインドを保存してbodyを評価し、以前に有効だったナローイング(またはナローイングのない状態)と同じ状態になるよう最後に保存されたバインドをリストアする。ナローイングの状態は、throwまたはエラーを通じたアブノーマルexit(非ローカル脱出を参照)イベント内においても、リストアされる。したがって、この構成は一時的にバッファーをナローする明快な手段である。

save-restrictionがリターンする値は、body内の最後のフォームのリターン値、またはbodyフォームが与えられなければnilである。

注意: save-restriction使用時は間違いを起こしやすい。これを試みる前にここでの説明全体を通読すること。

bodyがカレントバッファーを変更する場合でも、save-restrictionは依然として元のバッファー(その制限が保存されたバッファー)上の制限をリストアするが、カレントバッファー自体はリストアしない。

save-restriction does not restore point; use save-excursion for that. If you use both save-restriction and save-excursion together, save-excursion should come first (on the outside). Otherwise, the old point value would be restored with temporary narrowing still in effect. If the old point value were outside the limits of the temporary narrowing, this would fail to restore it accurately.

以下は、save-restrictionの正しい使い方の簡単な例である:

---------- Buffer: foo ----------
This is the contents of foo
This is the contents of foo
This is the contents of foo∗
---------- Buffer: foo ----------

(save-excursion
  (save-restriction
    (goto-char 1)
    (forward-line 2)
    (narrow-to-region 1 (point))
    (goto-char (point-min))
    (replace-string "foo" "bar")))

---------- Buffer: foo ----------
This is the contents of bar
This is the contents of bar
This is the contents of foo∗
---------- Buffer: foo ----------

31 マーカー

マーカー(marker)とは、あるバッファー内で取り囲んでいるテキストにたいして相対的な位置を指定するために使用されるオブジェクトです。テキストが挿入または削除されると常に、マーカーは自動的にそのバッファーの先頭からのオフセットを自動的に変更して、自身の左右にある文字の間に留まります。

31.1 マーカーの概要		マーカー構成要素と再配置方法。
31.2 マーカーのための述語		オブジェクトがマーカーか否かのテスト。
31.3 マーカーを作成する関数		空マーカーや特定箇所のマーカーの作成。
31.4 マーカーからの情報		マーカーのバッファーや文字位置を探す。
31.5 Marker 挿入タイプ		マーカーが指す位置への挿入時にマーカーを再配置する2つの方法。
31.6 マーカー位置の移動		新たなバッファーや位置にマーカーを移動する。
31.7 マーク		How the mark is implemented with a marker.
31.8 リージョン		How to access the region.

31.1 マーカーの概要

マーカーは、バッファーとそのバッファー内の位置を指定します。マーカーは、位置を要求する関数内において、位置を表すために整数と同じようにして使用することができます。その場合、そのマーカーのバッファーは、通常は無視されます。この方法で使用されるマーカーは通常、その関数が処理するバッファー内の位置を指しますが、それは完全にプログラマーの責任です。位置についての完全な説明は、ポジションを参照してください。

マーカーはマーカー位置(marker position)、マーカーバッファー(marker buffer)、挿入タイプ(insertion type)という3つの属性をもちます。マーカー位置は、そのバッファー内の位置としてのマーカーと、(その時点において)等しい整数です。しかし、マーカー位置はマーカー生存期間中に変化し得るものであり、頻繁に変化されます。バッファー内でのテキストの挿入や削除で、マーカーは再配置されます。マーカー前後の2文字以外の場所で挿入や削除がおこなわれても、マーカー位置はその2文字間に留まるというのが、このアイデアです。再配置により、マーカーと等価な整数は変更されます。

マーカー位置周辺のテキストを削除することにより、そのマーカーは削除されたテキストの直前および直後にある文字の間に残されます。マーカー位置へのテキスト挿入では、マーカーは通常は新たなテキストの前か後のいずれかに置かれます。その挿入がinsert-before-markers(テキストの挿入を参照)で行われたものでなければ、どちらに置かれるかはマーカーの挿入タイプ(Marker 挿入タイプを参照)に依存します。

バッファーでの挿入と削除では、すべてのマーカーをチェックして、必要ならそれらを再配置しなければなりません。これは、多数のマーカーをもつバッファーでの処理を遅くします。それ以上マーカーが不必要なのが確信できる場合には、存在しない場所も指さないようにマーカーを設定することは、この理由によりよいアイデアといえるでしょう。それ以上アクセスされる可能性がないマーカーは、最終的には削除されます(ガーベージコレクションを参照)。

マーカー位置にたいして算術演算を行うことは一般的なので、それらの演算子のほとんど(+や-を含む)が、引数としてマーカーに渡すことができます。そのような場合には、マーカーはカレント位置を意味します。

以下ではマーカー渡す作成とセットを行い、ポイントをマーカーに移動しています:

;; 最初はどこも指さない新たなマーカーを作成:
(setq m1 (make-marker))
     ⇒ #<marker in no buffer>

;; カレントバッファーの99と100番目の
;;   文字間を指すようm1をセット:
(set-marker m1 100)
     ⇒ #<marker at 100 in markers.texi>

;; ここでバッファー先頭に1文字挿入:
(goto-char (point-min))
     ⇒ 1
(insert "Q")
     ⇒ nil

;; m1は適切に更新された
m1
     ⇒ #<marker at 101 in markers.texi>

;; 同じ位置を指す2つのマーカーは
;;   equalだがeqに非ず
(setq m2 (copy-marker m1))
     ⇒ #<marker at 101 in markers.texi>
(eq m1 m2)
     ⇒ nil
(equal m1 m2)
     ⇒ t

;; マーカー使用終了時、存在しない場所を指すようセット
(set-marker m1 nil)
     ⇒ #<marker in no buffer>

31.2 マーカーのための述語

あるオブジェクトがマーカーなのか、それとも整数かマーカーのいずれかであるか確認するために、テストを行うことができます。後者のテストは、マーカーと整数の両方にたいして機能する算術関数において有用です。

Function: markerp object: この関数は、objectがマーカーならnil、それ以外はtをリターンする。多くの関数はマーカーか整数のいずれかを受け入れるだろうが、整数はマーカーと異なることに注意。

Function: integer-or-marker-p object: この関数は、objectが整数またはマーカーならt、それ以外はnilをリターンする。

Function: number-or-marker-p object: この関数は、objectが数値(整数か浮動小数点数のいずれか)またはマーカーならt、それ以外はnilをリターンする。

31.3 マーカーを作成する関数

マーカーを新たに作成する際は、存在しない場所、ポイントの現在位置、バッファーのアクセス可能範囲の先頭や終端、または別の与えられたマーカーと同じ箇所を指すようにすることができます。

以下の4つの関数はすべて、挿入タイプnilのマーカーをリターンします。Marker 挿入タイプを参照してください。

Function: make-marker

この関数は、どこも指さないマーカーを新たに作成してリターンする。

(make-marker)
     ⇒ #<marker in no buffer>

Function: point-marker: この関数は、カレントバッファーのポイント現在位置を指すマーカーを新たに作成してリターンする。See section ポイントを参照のこと。例は以下のcopy-markerを参照されたい。

Function: point-min-marker: この関数は、バッファーのアクセス可能範囲の先頭を指すマーカーを新たに作成してリターンする。ナローイングが効力をもたなければ、これはバッファーの先頭になるだろう。ナローイングを参照のこと。

Function: point-max-marker

この関数は、バッファーのアクセス可能範囲の終端を指すマーカーを新たに作成してリターンする。ナローイングが効力をもたなければ、これはバッファーの終端になるだろう。ナローイングを参照のこと。

以下に、このチャプターのテキストのソースファイルのバージョンを含むバッファーにたいして、この関数およびpoint-min-markerを使用した例を示す。

(point-min-marker)
     ⇒ #<marker at 1 in markers.texi>
(point-max-marker)
     ⇒ #<marker at 24080 in markers.texi>

(narrow-to-region 100 200)
     ⇒ nil

(point-min-marker)
     ⇒ #<marker at 100 in markers.texi>

(point-max-marker)
     ⇒ #<marker at 200 in markers.texi>

Function: copy-marker &optional marker-or-integer insertion-type

引数としてマーカーを渡されると、copy-markerはmarker-or-integerが行うようにして、同じバッファーの同じ位置を指すマーカーを新たに作成してリターンする。整数を渡された場合、copy-markerはカレントバッファーの位置marker-or-integerを指すマーカーを新たに作成してリターンする。

新たなマーカーの挿入タイプは、引数insertion-typeにより指定される。Marker 挿入タイプを参照のこと。

(copy-marker 0)
     ⇒ #<marker at 1 in markers.texi>

(copy-marker 90000)
     ⇒ #<marker at 24080 in markers.texi>

markerがマーカーと整数のいずれでもない場合は、エラーがシグナルされる。

2つのマーカーは、それらが同じバッファーの同じ位置、またはどちらも存在しない場所を指す場合は、(eqではないものの)equalとみなされます。

(setq p (point-marker))
     ⇒ #<marker at 2139 in markers.texi>

(setq q (copy-marker p))
     ⇒ #<marker at 2139 in markers.texi>

(eq p q)
     ⇒ nil

(equal p q)
     ⇒ t

31.4 マーカーからの情報

このセクションでは、マーカーオブジェクトの構成要素にアクセスする関数を説明します。

Function: marker-position marker: この関数は、markerが指す位置、または存在しない場所ならnilをリターンする。

Function: marker-buffer marker

この関数は、markerがその内部を指すバッファー、存在しない場所を指す場合はnilをリターンする。

(setq m (make-marker))
     ⇒ #<marker in no buffer>

(marker-position m)
     ⇒ nil

(marker-buffer m)
     ⇒ nil

(set-marker m 3770 (current-buffer))
     ⇒ #<marker at 3770 in markers.texi>

(marker-buffer m)
     ⇒ #<buffer markers.texi>

(marker-position m)
     ⇒ 3770

31.5 Marker 挿入タイプ

マーカーが指す位置に直接テキストを挿入する際、そのマーカーを再配置するために利用可能な手段が2つあります。そのマーカーはは挿入されたテキストの前、あるいは後を指すことができます。マーカーの挿入タイプ(insertion type)を指定することにより、マーカーがどちらを行うか指定できます。insert-before-markersを使用する場合は、マーカーの挿入タイプを無視して、常にマーカーが挿入されたテキストの後を指すよう再配置されることに注意してください。

Function: set-marker-insertion-type marker type: この関数は、マーカーmarkerの挿入タイプを、typeにセットする。typeがtの場合、テキスト挿入時にmarkerはその位置まで進められるだろう。typeがnilなら、テキスト挿入時にmarkerはそこまで進められない。

Function: marker-insertion-type marker: この関数は、markerのカレント挿入タイプを報告する。

All functions that create markers without accepting an argument that specifies the insertion type, create them with insertion type nil (see section マーカーを作成する関数). Also, the mark has, by default, insertion type nil.

31.6 マーカー位置の移動

このセクションでは、既存マーカーの位置を変更する方法について説明します。これを行う際は、そのマーカーがあなたのプログラム外部に使用されているかどうか、もし使用されているならマーカーを移動した結果どのような影響が生じるかを確実に理解する必要があります。さもないと、Emacsの他の部分で、混乱した出来事が発生するかもしれません。

Function: set-marker marker position &optional buffer

この関数は、buffer内でmarkerをpositionに移動する。bufferが与えられなかった場合のデフォルトは、カレントバッファーである。

positionがnil、または存在しない場所を指すマーカーの場合、markerは存在しない場所を指すようにセットされる。

リターン値はmarkerである。

(setq m (point-marker))
     ⇒ #<marker at 4714 in markers.texi>

(set-marker m 55)
     ⇒ #<marker at 55 in markers.texi>

(setq b (get-buffer "foo"))
     ⇒ #<buffer foo>

(set-marker m 0 b)
     ⇒ #<marker at 1 in foo>

Function: move-marker marker position &optional buffer: これはset-markerの別名である。

31.7 マーク

Each buffer has a special marker, which is designated the mark. When a buffer is newly created, this marker exists but does not point anywhere; this means that the mark doesn’t exist in that buffer yet. Subsequent commands can set the mark.

マークは、kill-regionやindent-rigidlyのような多くのコマンドにたいして、テキスト範囲をバインドするための位置を指定します。通常これらのコマンドは、ポイントとマークの間の、リージョン(region)と呼ばれるテキストに作用します。リージョンを操作するコマンドを記述する場合は、マークを直接調べず、かわりに‘r’指定とともにinteractiveを使用してください。このようにすれば、インタラクティブな呼び出しではコマンドの引数としてポイントとマークの値が提供され、かつ他のLispプログラムは引数を明示的に指定できます。interactiveにたいするコード文字を参照してください。

いくつかのコマンドは、その副作用(side-effect)としてマークをセットします。コマンドは、ユーザーがそれを使用する可能性がある場合のみマークをセットするべきであり、決してコマンドの内部的な目的にたいして使用してはなりません。たとえばreplace-regexpコマンドは、何らかの置換を行う前にマークにポイントの値をセットしますが、その理由はこれによりユーザーが置換を終えた後、簡単にその位置に戻ることが可能になるからです。

Once the mark exists in a buffer, it normally never ceases to exist. However, it may become inactive, if Transient Mark mode is enabled. The buffer-local variable mark-active, if non-nil, means that the mark is active. A command can call the function deactivate-mark to deactivate the mark directly, or it can request deactivation of the mark upon return to the editor command loop by setting the variable deactivate-mark to a non-nil value.

Transient Markモードが有効な場合、通常ならポイント近傍に適用される特定の編集コマンドは、マークがアクティブなときはかわりにリージョンに適用されます。これがTransient Markモードを使用する主な動機です(他にも、マークアクティブ時にはリージョンのハイライトが有効になるという理由もある。Emacsのディスプレー表示を参照されたい)。

マークに加えて、バッファーはそれぞれマークリング(mark ring)をもっています。これは、以前のマーク値を含むマーカーのリストです。編集コマンドがマークを変更する際、それらのコマンドは通常はマークの旧値をマークリングに保存するべきです。変数mark-ring-maxは、マークリング内のエントリー最大数を指定します。リストがこの長さに達すると、最後の要素を削除して、新たな要素が追加されます。

これとは別にグローバルマークリング(global mark ring)がありますが、それは少数の特定のユーザーレベルコマンドでのみ使用され、Lispプログラムとは関連しないので、ここでは説明しません。

Function: mark &optional force

この関数は、カレントバッファーのマーク位置を整数でリターンする。そのバッファー内でそれまでマークがセットされていなければnilをリターンする。

Transient Markモードが有効、かつmark-even-if-inactiveがnilの場合、マークが非アクティブならmarkはエラーをシグナルする。しかし、forceが非nilなら、markはマークの非アクティブ性を無視して、何にせよマーク位置(かnil)をリターンする。

Function: mark-marker

この関数は、カレントバッファーのマークを表すマーカーをリターンする。これはコピーではなく、内部的に使用されるマーカーである。したがって、このマーカー位置にたいする変更は、そのバッファーのマークに直接影響する。それが望む効果でなければ、これを行ってはならない。

(setq m (mark-marker))
     ⇒ #<marker at 3420 in markers.texi>

(set-marker m 100)
     ⇒ #<marker at 100 in markers.texi>

(mark-marker)
     ⇒ #<marker at 100 in markers.texi>

他のマーカー同様、このマーカーを任意のバッファー位置にセットできる。このマーカーに、これがマークする以外のバッファーを指すようにすると、完全に整合性があるものの、いささか奇妙な結果を得ることになるだろう。これを行わないことを、わたしたちは推奨する!

Function: set-mark position

この関数は、マークをpositionにセットして、そのマークをアクティブにする。マークの旧値はマークリングにpushされない。

注意: マークが移動したことをユーザーに確認させ、かつ前のマーク位置が失われることを望む場合のみ、この関数を使用すること。通常は、マークセット時に古いマークはmark-ringにpushされるべきである。この理由により、ほとんどのアプリケーションはset-markではなく、push-markおよびpop-markを使用するべきである。

Emacs Lispの初心者プログラマーは、誤った用途にマークの使用を試みがちである。ユーザーの利便のために位置を保存するのがマークである。編集コマンドは、マーク変更がコマンドのユーザーレベル機能の一部でない限り、マークを変更するべきではない(そして、そのような場合にはその効果をドキュメントするべきである)。Lispプログラムの内部的な使用のために位置を記憶するためには、マークをLisp変数に格納すること。たとえば:

(let ((beg (point)))
  (forward-line 1)
  (delete-region beg (point)))

Function: push-mark &optional position nomsg activate

この関数は、カレントバッファーのマークをpositionにセットして、前のマークをmark-ringにpushする。positionがnilの場合は、ポイントの値を使用する。

関数push-markは通常、マークをアクティブにしない。アクティブにする場合は、引数activateにtを指定する。

nomsgがnilなら、メッセージ‘Mark set’が表示される。

Function: pop-mark: この関数は、mark-ringのトップ要素をpopして、そのマークをバッファーの実際のマークにする。これはバッファー内のポイントを移動せず、mark-ringが空なら何も行わない。これはマークを非アクティブ化する。

User Option: transient-mark-mode

この変数が非nilなら、Transient Markモードを有効にする。Transient Markモードでは、すべてのバッファー変更プリミティブがdeactivate-markをセットする。結果として、バッファーを変更するほとんどのコマンドも、マークを非アクティブにする。

Transient Markモードが有効かつマークがアクティブの場合、通常はポイント近傍に適用されるコマンドの多くは、かわりにリージョンに適用される。そのようなコマンドは、リージョンを処理すべきかどうかをテストするために、関数use-region-pを使用するべきである。リージョンを参照のこと。

Lispプログラムは、一時的にTransient Markモードを有効にするために、transient-mark-modeをnilでもtでもない値にセットできる。値がlambdaなら、バッファー変更のような通常ならマークを非アクティブ化するような操作の後、Transient Markモードを自動的にオフに切り替える。値が(only . oldval)なら、後続のコマンドがポイントを移動かつシフト変換(shift-translationを参照)されていない場合、あるいは通常はマークを非アクティブにするその他の操作の場合は、transient-mark-modeに値oldvalをセットする。

User Option: mark-even-if-inactive: これが非nilなら、LispプログラムおよびEmacsユーザーは、たとえ非アクティブでもマークを使用できる。このオプションは、Transient Markモードの動作に影響を及ぼす。このオプションが非nilなら、マークの非アクティブ化によりリージョンのハイライトはオフに切り替えられるが、マークを使用するコマンドは、あたかもマークがアクティブであるかのように振る舞う。

Variable: deactivate-mark

If an editor command sets this variable non-nil, then the editor command loop deactivates the mark after the command returns (if Transient Mark mode is enabled). All the primitives that change the buffer set deactivate-mark, to deactivate the mark when the command is finished. Setting this variable makes it buffer-local.

コマンド終了時にマークを非アクティブにすることなくバッファーを変更するLispコードを記述するためには、変更を行うコードの周辺でdeactivate-markをnilにバインドすること。たとえば:

(let (deactivate-mark)
  (insert " "))

Function: deactivate-mark &optional force: Transient Markモードが有効、またはforceが非nilの場合、この関数はマークを非アクティブにしてノーマルフックdeactivate-mark-hookを実行し、それ以外は何も行わない。

Variable: mark-active: この変数が非nilなら、マークはアクティブである。この変数は、それぞれのバッファーにたいして、常にローカルである。通常はポイント近傍を操作するコマンドが、かわりにリージョンを操作すべきかどうかを判断するために、この変数の値を使用してはならない。その目的にたいしては、関数use-region-pを使用すること(リージョンを参照)。

Variable: activate-mark-hook
Variable: deactivate-mark-hook: これらのノーマルフックは、マークがアクティブまたは非アクティブになった際に、順次実行される。マークがアクティブで、かつリージョンが変更された可能性があるなら、コマンドループの最後にフックactivate-mark-hookも実行される。

Function: handle-shift-selection

This function implements the shift-selection behavior of point-motion commands. See Shift Selection in The GNU Emacs Manual. It is called automatically by the Emacs command loop whenever a command with a ‘^’ character in its interactive spec is invoked, before the command itself is executed (see section ^).

shift-select-modeが非nil、かつカレントコマンドがシフト変換(shift-translationを参照)を通じて呼び出された場合、この関数はマークをセットして一時的にリージョンをアクティブにする(すでにこの方法によりリージョンが一時的にアクティブにされている場合を除く)。それ以外では、リージョンが一時的にアクティブにされていれば、マークを非アクティブにして、変数transient-mark-modeに前の値をリストアする。

Variable: mark-ring

このバッファーローカル変数の値は、もっとも最近のものが先頭となった、カレントバッファーの以前に保存されたマークのリストである。

mark-ring
⇒ (#<marker at 11050 in markers.texi>
    #<marker at 10832 in markers.texi>
    …)

User Option: mark-ring-max: この変数の値は、mark-ringの最大サイズである。これより多くのマークがmark-ringにpushされると、新たなマーク追加時にpush-markは古いマークを破棄する。

When Delete Selection mode (see Delete Selection in The GNU Emacs Manual) is enabled, commands that operate on the active region (a.k.a. “selection”) behave slightly differently. This works by adding the function delete-selection-pre-hook to the pre-command-hook (see section コマンドループの概要). That function calls delete-selection-helper to delete the selection as appropriate for the command. If you want to adapt a command to Delete Selection mode, put the delete-selection property on the function’s symbol (see section シンボルのプロパティへのアクセス); commands that don’t have this property on their symbol won’t delete the selection. This property can have one of several values to tailor the behavior to what the command is supposed to do; see the doc strings of delete-selection-pre-hook and delete-selection-helper for the details.

31.8 リージョン

ポイントとマークの間のテキストは、リージョン(region)という名で知られています。さまざまな関数がポイントとマークで区切られたテキストを操作しますが、ここではリージョンそのものに特に関連する関数だけを説明します。

以下の2つの関数は、マークが何処も指していなければエラーをシグナルします。Transient Markモードが有効、かつmark-even-if-inactiveがnilなら、マークが非アクティブな場合のエラーをシグナルします。

Function: region-beginning: この関数は、リージョンの先頭位置を、(整数として)リターンする。これは、ポイントかマークのいずれか小さいほうの位置である。

Function: region-end: この関数は、リージョンの終端位置を、(整数として)リターンする。これは、ポイントかマークのいずれか大きいほうの位置である。

リージョンにたいして操作を行うようにデザインされたコマンドがリージョンの先頭と終端を探すには、region-beginningおよびregion-endを使用するかわりに、通常は‘r’指定とともにinteractiveを使用するべきです。これにより、他のLispプログラムが引数として明示的にリージョンの境界を指定できるようになります。interactiveにたいするコード文字を参照してください。。

Function: use-region-p

この関数は、Transient Markモードが有効でマークがアクティブであり、かつバッファー内に有効なリージョンがあればtをリターンする。この関数は、マークアクティブ時にはポイント近傍のテキストのかわりにリージョンを操作するコマンドにより使用されることを意図している。

リージョンは、それが非0のサイズをもつか、あるいはユーザーオプションuse-empty-active-regionが非nil(デフォルトはnil)なら有効である。関数region-active-pはuse-region-pと同様だが、すべてのリージョンを有効とみなす。リージョンが空ならポイントにたいして操作を行うほうが適切な場合が多いため、ほとんどの場合はregion-active-pを使用するべきではない。

32 テキスト

このチャプターでは、バッファー内のテキストを扱う関数を説明します。ほとんどはカレントバッファー内のテキストにたいして検査、挿入、削除を行い、ポイント位置やポイントに隣接するテキストを操作することが多々あります。その多くはインタラクティブ(interactive: 対話的)です。テキストを変更するすべての関数は、その変更にたいするundo(アンドゥ、取り消し)を提供します(アンドゥを参照)。

テキストに関連する関数の多くが、startおよびendという名前の引数として渡された、2つのバッファー位置により定義された、テキストのリージョンを操作します。これらの引数は、マーカー(マーカーを参照)か、数値的な文字位置(ポジションを参照)のいずれかであるべきです。これらの引数の順序は関係ありません。startがリージョンの終端で、endがリージョンの先頭であっても、何も問題はないのです。たとえば、(delete-region 1 10)と(delete-region 10 1)は等価です。startとendのいずれかが、バッファーのアクセス可能範囲の外部なら、args-out-of-rangeエラーがシグナルされます。インタラクティブな呼び出しでは、これらの引数にポイントとマークが使用されます。

このチャプターを通じて、“テキスト(text)”とは(関係あるときは)そのプロパティも含めた、バッファー内の文字を意味します。ポイントは常に2つの文字の間にあり、カーソルはポイントの後の文字上に表示されることを覚えておいてください。

32.1 ポイント周辺のテキストを調べる		ポイント付近のテキストを調べる。
32.2 バッファーのコンテンツを調べる		一般的な方法によってテキストを調べる。
32.3 テキストの比較		バッファーの部分文字列を比較する。
32.4 テキストの挿入		バッファーへの新たなテキストの追加。
32.5 ユーザーレベルの挿入コマンド		テキスト挿入のためのユーザーレベルコマンド。
32.6 テキストの削除		バッファーからテキストを削除する。
32.7 ユーザーレベルの削除コマンド		テキスト削除のためのユーザーレベルコマンド。
32.8 killリング		テキスト削除時にユーザーのためにそれを保存する場所。
32.9 アンドゥ		バッファーのテキストにたいする変更の取り消し。
32.10 アンドゥリストの保守		undo情報の有効と無効。情報をどれだけ保持するか制御する方法。
32.11 fill		明示的にフィルを行う関数。
32.12 fillのマージン		フィルコマンドにたいしてマージンを指定する方法。
32.13 Adaptive Fillモード		コンテキストからフィルプレフィクスを選択するAdaptive Fillモード。
32.14 オートfill		行ブレークにたいするauto-fillの実装方法。
32.15 テキストのソート		バッファーの一部をソートする関数。
32.16 列を数える		水平位置の計算とその使用方法。
32.17 インデント		インデントの挿入や調整のための関数。
32.18 大文字小文字の変更		バッファーの一部にたいする大文字小文字変換。
32.19 テキストのプロパティ		テキスト文字にたいするLispプロパティリストの追加。
32.20 文字コードの置き換え		与ええられた文字の出現箇所を置換する。
32.21 レジスター		レジスターの実装方法。レジスターに格納されたテキストや位置にアクセスする。
32.22 テキストの交換		バッファーの2つの部分を交換する。
32.23 Replacing Buffer Text		Replacing the text of one buffer with the text of another buffer.
32.24 圧縮されたデータの処理		圧縮データの扱い。
32.25 Base 64エンコーディング		Base64エンコーディングとの変換。
32.26 チェックサムとハッシュ		暗号ハッシュの計算。
32.27 GnuTLS Cryptography		Cryptographic algorithms imported from GnuTLS.
32.28 HTMLとXMLの解析		HTMLおよびXMLの解析。
32.29 グループのアトミックな変更		Installing several buffer changes atomically.
32.30 フックの変更		テキスト変更時に実行する関数の指定。

32.1 ポイント周辺のテキストを調べる

ポイント付近にある文字を調べるための関数が、数多く提供されています。簡単な関数のいくつかは、ここで説明します。正規表現の検索のlooking-atも参照してください。

以下の4つの関数においてバッファーの“先頭(beginning)”と“終端(end)”はそれぞれ、アクセス可能範囲の先頭と終端を意味します。

Function: char-after &optional position

この関数は、カレントバッファーの位置position(つまり直後)の文字をリターンする。positionが、この目的にたいする範囲の外にある場合、すなわちバッファーの先頭より前、またはバッファーの終端以降にある場合、値はnilとなる。positionのデフォルトは、ポイントである。

以下の例では、バッファーの最初の文字が‘@’であると仮定する:

(string (char-after 1))
     ⇒ "@"

Function: char-before &optional position: この関数は、カレントバッファーの位置positionの直前の文字をリターンする。positionが、この目的にたいする範囲の外にある場合、すなわちバッファーの先頭より前、またはバッファーの終端より後にある場合、値はnilとなる。positionのデフォルトは、ポイントである。

Function: following-char

この関数は、カレントバッファーのポイントの後にある文字をリターンする。これは(char-after (point))と同様。ただし、ポイントがバッファー終端にある場合、following-charは0をリターンする。

ポイントが常に2文字間にあり、通常カーソルはポイント後の文字上に表示されることを思い出していただきたい。したがって、following-charがリターンする文字は、カーソル上の文字となる。

以下の例では、‘a’と‘c’の間にポイントがある。

---------- Buffer: foo ----------
Gentlemen may cry ``Pea∗ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(string (preceding-char))
     ⇒ "a"
(string (following-char))
     ⇒ "c"

Function: preceding-char: この関数は、カレントバッファーのポイントの前の文字をリターンする。上記following-charの下の例を参照されたい。ポイントがバッファー先頭にある場合、preceding-charは0をリターンする。

Function: bobp: この関数は、ポイントがバッファー先頭にあればtをリターンする。ナローイングが効力をもつ場合、これはテキストのアクセス可能範囲の先頭を意味する。ポイントのpoint-minも参照のこと。

Function: eobp: この関数は、ポイントがバッファー終端にあればtをリターンする。ナローイングが効力をもつ場合、これはテキストのアクセス可能範囲の終端を意味する。ポイントのpoint-maxも参照のこと。

Function: bolp: この関数は、ポイントが行の先頭にあればtをリターンする。テキスト行単位の移動を参照のこと。バッファー(またはアクセス可能範囲)の先頭は、常に行の先頭とみなされる。

Function: eolp: この関数は、ポイントが行の終端にあればtをリターンする。テキスト行単位の移動を参照のこと。バッファー(またはアクセス可能範囲)の終端は、常に行の先頭とみなされる。

32.2 バッファーのコンテンツを調べる

このセクションでは、Lispプログラムがバッファー内の任意の範囲のテキストを、文字列に変換するための関数を説明します。

Function: buffer-substring start end

この関数は、カレントバッファー内の位置startとendで定義されるリージョンのテキストのコピーを含む文字列をリターンする。引数がバッファーのアクセス可能範囲内の位置でない場合、buffer-substringはargs-out-of-rangeエラーをリターンする。

以下の例では、Font-Lockモードが有効でないものとする:

---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
     ⇒ "This is t"

(buffer-substring (point-max) 10)
     ⇒ "he contents of buffer foo\n"

コピーされるテキストが何らかのテキストプロパティをもっていた場合、それらのプロパティが属す文字とともに文字列にコピーされる。しかし、バッファー内のオーバーレイ(オーバーレイを参照)、およびそれらのプロパティは無視されるため、コピーされない。

たとえば、Font-Lockモードが有効なら、以下のような結果を得るだろう:

(buffer-substring 1 10)
     ⇒ #("This is t" 0 1 (fontified t) 1 9 (fontified t))

Function: buffer-substring-no-properties start end: これはbuffer-substringと同様だが、テキストプロパティはコピーせず、文字自体だけをコピーする点が異なる。テキストのプロパティを参照のこと。

Function: buffer-string: この関数は、カレントバッファーのアクセス可能範囲全体のコンテンツを、文字列としてリターンする。

If you need to make sure the resulting string, when copied to a different location, will not change its visual appearance due to reordering of bidirectional text, use the buffer-substring-with-bidi-context function (see section buffer-substring-with-bidi-context).

Function: filter-buffer-substring start end &optional delete

この関数は、変数filter-buffer-substring-functionにより指定された関数を使用して、startとendの間のバッファーテキストをフィルターし、その結果をリターンする。

The default filter function consults the obsolete wrapper hook filter-buffer-substring-functions (see the documentation string of the macro with-wrapper-hook for the details about this obsolete facility), and the obsolete variable buffer-substring-filters. If both of these are nil, it returns the unaltered text from the buffer, i.e., what buffer-substring would return.

deleteが非nilなら、この関数はdelete-and-extract-regionと同様、コピー後にstartとendの間のテキストを削除する。

Lispコードは、killリング、Xクリップボード、レジスターのようなユーザーがアクセス可能なデータ構造内にコピーする際はbuffer-substring、buffer-substring-no-properties、delete-and-extract-regionのかわりにこの関数を使用するべきである。メジャーモードおよびマイナーモードは、バッファー外部にコピーするテキストを変更するためにfilter-buffer-substring-functionを変更することができる。

Variable: filter-buffer-substring-function: この変数の値は、実際の処理を行うためにfilter-buffer-substringが呼び出す関数である。その関数は、filter-buffer-substringと同じように3つの引数を受けとり、それらはfilter-buffer-substringにドキュメントされているように扱われるべきである。関数は、フィルターされたテキストをリターン(およびオプションでソーステキストを削除)すること。

以下の2つの変数は、filter-buffer-substring-functionにより時代遅れになりましたが、後方互換のために依然サポートされます。

Variable: filter-buffer-substring-functions

これは時代遅れとなったラッパーフックであり、このフックのメンバーはfun、start、end、deleteの4つの引数を受け取る関数であること。funは3つの引数(start、end、delete)をとり、文字列をリターンする関数である。両者とも、引数start、end、deleteはfilter-buffer-substringのときと同様の意味をもつ。

1つ目のフック関数はfilter-buffer-substringのデフォルトの処理と同じくstartとendの間の(任意のbuffer-substring-filtersにより処理された)バッファー部分文字列をリターンし、オプションでバッファーから元テキストを削除する関数で、それがfunに渡される。ほとんどの場合、フック関数はfunを1回だけ呼び出してから、その結果にたいして自身の処理を行う。次のフック関数はこれと等しいfunを受け取り、順次それが繰り返されていく。実際のリターン値は、すべてのフック関数が順次処理した結果である。

Variable: buffer-substring-filters: 時代遅れとなったこの変数の値は、文字列を唯一の引数ちして別の文字列をリターンする関数のリストであること。デフォルトのfilter-buffer-substring関数は、バッファー部分文字列をこのリストの1つ目の関数に渡し、そのリターン値を次の関数に渡して、それぞれの関数にたいしてこれが順次繰り返される。最後の関数のリターン値は、filter-buffer-substring-functionsに渡される。

Function: current-word &optional strict really-word

この関数は、ポイント位置またはその付近のシンボル(または単語)を、文字列としてリターンする。リターン値にはテキストプロパティは含まれない。

オプション引数really-wordが非nilなら単語、それ以外はシンボル(単語文字とシンボル構成文字の両方を含む)を探す。

オプション引数strictが非nilの場合、ポイントは単語(またはシンボル)の内部にあるか隣接しなければならない。そこに単語(またはシンボル)がなければ、この関数はnilをリターンする。strictがnilなら、ポイントと同一行にある近接する単語(またはシンボル)が許容される。

Function: thing-at-point thing &optional no-properties

ポイントに隣接または周辺にあるthingを、文字列としてリターンする。

引数thingは、構文エンティティの種別を指定するシンボルである。可能なシンボルとしてはsymbol、list、sexp、defun、filename、url、word、sentence、whitespace、line、page、その他が含まれる。

When the optional argument no-properties is non-nil, this function strips text properties from the return value.

---------- Buffer: foo ----------
Gentlemen may cry ``Pea∗ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
     ⇒ "Peace"
(thing-at-point 'line)
     ⇒ "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
     ⇒ nil

32.3 テキストの比較

この関数により、最初にバッファー内のテキストを文字列内にコピーすることなく、バッファー内のテキスト断片を比較することが可能になります。

Function: compare-buffer-substrings buffer1 start1 end1 buffer2 start2 end2

この関数により、1つのバッファー、または2つの異なるバッファーの、2つの部分文字列(substrings)を比較できる。最初の3つの引数は、バッファーとそのバッファー内の2つの位置を与えることにより、1つの部分文字列を指定する。最後の3つの引数は、同様の方法によりもう一方の部分文字列を指定する。buffer1とbuffer2のいずれか、または両方にたいして、カレントバッファーを意味するnilを使用できる。

1つ目の部分文字列が2つ目の部分文字列より小なら負、大なら正、等しければ値は0となる。結果の絶対値は、部分文字列内で最初に異なる文字のインデックスに1を和した値である。

case-fold-searchが非nilなら、この関数は大文字小文字の違いを無視する。テキストプロパティは常に無視される。

カレントバッファー内にテキスト‘foobarbar haha!rara!’があるとしよう。そしてこの例では2つの部分文字列が‘rbar’と‘rara!’であるとする。1つ目の文字列の2つ目の文字が大きいので、値は2となる。

(compare-buffer-substrings nil 6 11 nil 16 21)
     ⇒ 2

32.4 テキストの挿入

挿入(insertion)とは、バッファーへの新たなテキストの追加を意味します。テキストはポイント位置、すなわちポイント前の文字とポイント後の文字の間に追加されます。挿入関数は挿入されたテキストの後にポイントを残しますが、前にポイントを残す関数もいくつかあります。前者の挿入をポイント後挿入(after point)、後者をポイント前挿入(before point)と呼びます。

挿入により、挿入位置の後にあったマーカーは、テキストを取り囲むように移動されます(マーカーを参照)。マーカーは挿入箇所をさしている際は、挿入によるマーカー再配置の有無は、そのマーカーの挿入タイプに依存します(Marker 挿入タイプを参照)。insert-before-markersのような特定のスペシャル関数は、マーカーの挿入タイプとは関係なく、挿入されたテキストの後にそのようなマーカーすべてを再配置します。

カレントバッファーが読み取り専用(読み取り専用のバッファーを参照)、または読み取り専用テキスト(特殊な意味をもつプロパティを参照)を挿入しようとした場合、挿入関数はエラーをシグナルします。

以下の関数は、文字列およびバッファーからプロパティとともにテキスト文字をコピーします。挿入される文字は、コピー元の文字と完全に同一のプロパティをもちます。それとは対照的に、文字列やバッファーの一部ではない個別の引数として指定された文字は、隣接するテキストからテキストプロパティを継承します。

テキストが文字列またはバッファー由来の場合、マルチバイトバッファーに挿入するために、挿入関数はユニバイトからマルチバイトへの変換、およびその逆も行います。しかし、たとえカレントバッファーがマルチバイトバッファーであったとしても、コード128から255までのユニバイトはマルチバイトに変換しません。テキスト表現の変換を参照してください。

Function: insert &rest args: この関数は、文字列および/または1つ以上の文字argsを、カレントバッファーのポイント位置に挿入して、ポイントを前方に移動する。言い換えると、ポイントの前にテキストを挿入する。すべてのargsが文字列が文字列と文字のいずれでもない場合は、エラーをシグナルする。値はnil。

Function: insert-before-markers &rest args

この関数は、文字列および/または1つ以上の文字argsを、カレントバッファーのポイント位置に挿入して、ポイントを前方に移動する。すべてのargsが文字列が文字列と文字のいずれでもない場合は、エラーをシグナルする。値はnil。

他の挿入関数と異なり、この関数は挿入されたテキストの後を指すように、まずマーカーが挿入位置を指すように再配置する。挿入位置からオーバーレイが開始される場合、挿入されたテキストはそのオーバーレイの外側に出される。空でないオーバーレイが挿入位置で終わる場合、挿入されたテキストはそのオーバーレイの内側に入れられる。

Command: insert-char character &optional count inherit

このコマンドは、カレントバッファーのポイントの前に、characterのインスタンスをcount個挿入する。引数countは整数、characterは文字でなければならない。

インタラクティブに呼び出された際は、このコマンドはcharacterにたいしてコードポイントかUnicode名による入力を求める。Inserting Text in The GNU Emacs Manualを参照のこと。

この関数は、たとえカレントバッファーがマルチバイトバッファーであっても、コード128から255のユニバイト文字をマルチバイト文字に変換しない。テキスト表現の変換を参照のこと。

inheritが非nilの場合、挿入された文字は挿入位置前後の2文字から、ステッキーテキストプロパティ(sticky text properties)を継承する。テキストプロパティの粘着性を参照のこと。

Function: insert-buffer-substring from-buffer-or-name &optional start end

この関数は、カレントバッファーのポイント前に、バッファーfrom-buffer-or-nameの一部を挿入する。挿入されるテキストは、start(を含む)からend(を含まない)の間のリージョン(これらの引数のデフォルトは、そのバッファーのアクセス可能範囲の先頭と終端)である。この関数はnilをリターンする。

以下の例では、バッファー‘bar’をカレントバッファーとしてフォームを実行する。バッファー‘bar’は、最初は空であるものとする。

---------- Buffer: foo ----------
We hold these truths to be self-evident, that all
---------- Buffer: foo ----------

(insert-buffer-substring "foo" 1 20)
     ⇒ nil

---------- Buffer: bar ----------
We hold these truth∗
---------- Buffer: bar ----------

Function: insert-buffer-substring-no-properties from-buffer-or-name &optional start end: これはinsert-buffer-substringと似ているが、テキストプロパティをコピーしない点が異なる。

テキスト挿入に加えて、隣接するテキストからテキストプロパティを継承する他の関数については、テキストプロパティの粘着性を参照のこと。インデント関数により挿入された空白文字も、テキストプロパティを継承する。

32.5 ユーザーレベルの挿入コマンド

このセクションでは、テキスト挿入のための高レベルコマンド、ユーザーによる使用を意図しているがLispプログラムでも有用なコマンドについて説明します。

Command: insert-buffer from-buffer-or-name: このコマンドは、from-buffer-or-name(存在しなければならない)のアクセス可能範囲全体を、カレントバッファーのポイントの後に挿入する。マークは挿入されたテキストの後に残される。値はnil。

Command: self-insert-command count

このコマンドは、タイプされた最後の文字を挿入する。これをポイント前でcount回繰り返して、nilをリターンする。ほとんどのプリント文字が、このコマンドにバインドされる。通常の使用では、self-insert-commandはEmacsでもっとも頻繁に呼び出される関数だが、Lispプログラムではそれをキーマップにインストールする場合を除き、使用されるのは稀である。

インタラクティブな呼び出しでは、countは数プレフィクス引数である。

自己挿入では、入力文字はtranslation-table-for-inputを通じて変換される。文字の変換を参照のこと。

これは、入力文字がテーブルauto-fill-chars内にあり、auto-fill-functionが非nilなら、常にそれを呼び出す(オートfillを参照)。

This command performs abbrev expansion if Abbrev mode is enabled and the inserted character does not have word-constituent syntax. (See section abbrevとabbrev展開, and 構文クラスのテーブル.) It is also responsible for calling blink-paren-function when the inserted character has close parenthesis syntax (see section カッコの点滅).

The final thing this command does is to run the hook post-self-insert-hook. You could use this to automatically reindent text as it is typed, for example. If any function on this hook needs to act on the region (see section リージョン), it should make sure Delete Selection mode (see Delete Selection in The GNU Emacs Manual) doesn’t delete the region before post-self-insert-hook functions are invoked. The way to do so is to add a function that returns nil to self-insert-uses-region-functions, a special hook that tells Delete Selection mode it should not delete the region.

self-insert-commandの標準的な定義にたいして、独自の定義による置き換えを試みてはならない。エディターコマンドループは、このコマンドを特別に扱うからだ。

Command: newline &optional number-of-newlines

このコマンドは、カレントバッファーのポイントの前に、改行を挿入する。number-of-newlinesが与えられた場合は、その個数の改行文字が挿入される。

この関数は、カレント列数がfill-columnより大、かつnumber-of-newlinesがnilなら、auto-fill-functionを呼び出す。auto-fill-functionが通常行うのは改行の挿入ではり、最終的な結果としては、ポイント位置と、その行のより前方の位置という、2つの異なる箇所に改行を挿入する。number-of-newlinesが非nilなら、newlineはauto-fillを行わない。

このコマンドは、左マージンが0でなければ、左マージンにインデントする。fillのマージンを参照のこと。

リターン値はnil。インタラクティブな呼び出しでは、countは数プレフィクス引数である。

Variable: overwrite-mode: この変数は、overwriteモードに効力をもつかどうかを制御する。値はoverwrite-mode-textual、overwrite-mode-binary、またはnilであること。overwrite-mode-textualはテキスト的なoverwriteモード(改行とタブを特別に扱う)、overwrite-mode-binaryはバイナリーoverwriteモード(改行とタブを普通の文字と同様に扱う)を指定する。

32.6 テキストの削除

削除とは、バッファー内のテキストの一部を、killリングに保存せずに取り除くことを意味します。(killリングを参照)。削除されたテキストをyankすることはできませんが、undoメカニズム(アンドゥを参照)を使用すれば再挿入が可能です。特別なケースにおいては、killリングにテキストの保存を行う削除関数がいくつかあります。

削除関数はすべて、カレントバッファーにたいして処理を行います。

Command: erase-buffer

この関数は、カレントバッファーのテキスト全体(アクセス可能範囲だけではない)を削除してバッファーが読み取り専用ならbuffer-read-only、バッファー内の一部テキストが読み取り専用の場合はtext-read-onlyをシグナルする。それ以外では、確認なしでテキストを削除する。リターン値はnil。

Normally, deleting a large amount of text from a buffer inhibits further auto-saving of that buffer because it has shrunk. However, erase-buffer does not do this, the idea being that the future text is not really related to the former text, and its size should not be compared with that of the former text.

Command: delete-region start end: このコマンドは、カレントバッファー内の位置startからendまでの間のテキストを削除して、nilをリターンする。削除されるリージョン内にポイントがある場合、リージョン削除後のポイントの値はstartになる。それ以外の場合は、マーカーが行うようにポイントはテキストを取り囲むように再配置される。

Function: delete-and-extract-region start end

この関数は、カレントバッファー内の位置startからendまでの間のテキストを削除して、削除されたテキストを含む文字列をリターンする。

削除されるリージョン内にポイントがある場合、リージョン削除後のポイントの値はstartになる。それ以外の場合は、マーカーが行うようにポイントはテキストを取り囲むように再配置される。

Command: delete-char count &optional killp

このコマンドは、ポイント直後のcount文字、countが負なら直前のcount文字を削除する。killpが非nilなら、削除した文字をkillリングに保存する。

インタラクティブな呼び出しでは、countは数プレフィクス引数、killpは未処理プレフィクス引数(unprocessed prefix argument)である。すなわち、プレフィクス引数が与えられた場合、そのテキストはkillリングに保存され、与えられなければ、1文字が削除され、それはkillリングに保存されない。

リターン値は常にnilである。

Command: delete-backward-char count &optional killp

このコマンドは、ポイント直前のcount文字、countが負なら直後のcount文字を削除する。killpが非nilなら、削除した文字をkillリングに保存する。

リターン値は常にnilである。

Command: backward-delete-char-untabify count &optional killp

このコマンドは、タブをスペースに変換しながら、後方にcount文字を削除する。次に削除する文字がタブなら、まず適正な位置を保つような数のスペースに変換してから、それらのうちのスペース1つをタブのかわりに削除する。killpが非nilなら、このコマンドは削除した文字をkillリングに保存する。

タブからスペースへの変換は、countが正の場合のみ発生する。負の場合は、ポイント後の-count文字が、正確に削除される。

リターン値は常にnilである。

User Option: backward-delete-char-untabify-method: このオプションは、backward-delete-char-untabifyが空白文字を扱う方法を指定する。可能な値にはuntabify(タブを個数分のスペースに変換してスペースを1つ削。これがデフォルト除)、hungry(1コマンドでポイント前のタブとスペースすべてを削除する)、all(ポイント前のタブとスペース、および改行すべてを削除する)、nil(空白文字にたいして特に何もしない)。

32.7 ユーザーレベルの削除コマンド

このセクションでは、主にユーザーにたいして有用なものの、Lispプログラムでも有用な、テキストを削除するための高レベルんｑコマンドを説明します。

Command: delete-horizontal-space &optional backward-only

この関数は、ポイント近辺のすべてのスペースとタブを削除する。リターン値はnil。

backward-onlyが非nilの場合、この関数はポイント前のスペースとタブを削除するがポイント後のスペースとタブは削除しない。

以下の例では、各行ごとに、2番目と3番目の間にポイントを置いて、delete-horizontal-spaceを4回呼び出している。

---------- Buffer: foo ----------
I ∗thought
I ∗     thought
We∗ thought
Yo∗u thought
---------- Buffer: foo ----------

(delete-horizontal-space)   ; Four times.
     ⇒ nil

---------- Buffer: foo ----------
Ithought
Ithought
Wethought
You thought
---------- Buffer: foo ----------

Command: delete-indentation &optional join-following-p

この関数は、ポイントのある行を、その前の行に結合(join)する。結合においては、すべての空白文字を削除、特定のケースにおいてはそれらを1つのスペースに置き換える。join-following-pが非nilなら、delete-indentationはかわりに後続行と結合を行う。この関数はnilをリターンする。

fillプレフィクスがあり、結合される2つ目の行もそのプレフィクスで始まる場合、行の結合前にdelete-indentationはそのfillプレフィクスを削除する。fillのマージンを参照のこと。

以下の例では、‘events’で始まる行にポイントがあり、前の行の末尾に1つ以上のスペースが存在しても、違いは生じない。

---------- Buffer: foo ----------
When in the course of human
∗    events, it becomes necessary
---------- Buffer: foo ----------


(delete-indentation)
     ⇒ nil

---------- Buffer: foo ----------
When in the course of human∗ events, it becomes necessary
---------- Buffer: foo ----------

行の結合後に、結合点に単一のスペースを残すか否かを決定するのは、関数fixup-whitespaceの責任である。

Command: fixup-whitespace

この関数は、ポイントを取り囲むすべての水平スペースを、コンテキストに応じて1つのスペースまたはスペースなしに置き換える。リターン値はnil。

行の先頭または末尾において、スペースの適正な数は0である。閉じカッコ構文(close parenthesis syntax)の前の文字、開きカッコの後の文字、式プレフィクス構文(expression-prefix syntax)においても、スペースの適正な数は0である。それ以外では、スペースの適正な数は1である。構文クラスのテーブルを参照のこと。

以下の例では、最初に1行目の単語‘spaces’の前にポイントがある状態で、fixup-whitespaceを呼び出している。2回目の呼び出しでは、‘(’の直後にポイントがある。

---------- Buffer: foo ----------
This has too many     ∗spaces
This has too many spaces at the start of (∗   this list)
---------- Buffer: foo ----------

(fixup-whitespace)
     ⇒ nil
(fixup-whitespace)
     ⇒ nil

---------- Buffer: foo ----------
This has too many spaces
This has too many spaces at the start of (this list)
---------- Buffer: foo ----------

Command: just-one-space &optional n: このコマンドは、ポイントを取り囲むすべてのスペースを1つのスペース、またはnが指定された場合はn個のスペースで置き換える。リターン値はnil。

Command: delete-blank-lines

この関数は、ポイントを取り囲む空行を削除する。ポイントが前後に1行以上の空行がある空の行にある場合は、1行を除きそれらすべてを削除する。ポイントが孤立した空行にあるなら、その行を削除する。ポイントが空でない行にあるなら、その直後にあるすべての空白を削除する。

空行とは、タブまたはスペースのみを含む行として定義される。

delete-blank-linesはnilをリターンする。

Command: delete-trailing-whitespace &optional start end

startとendで定義されるリージョン内の、末尾の空白文字を削除する。

このコマンドは、リージョン内の各行の最後の非空白文字後にある空白文字を削除する。

If this command acts on the entire buffer (i.e., if called interactively with the mark inactive, or called from Lisp with end nil), it also deletes all trailing lines at the end of the buffer if the variable delete-trailing-lines is non-nil.

32.8 killリング

Kill functions delete text like the deletion functions, but save it so that the user can reinsert it by yanking. Most of these functions have ‘kill-’ in their name. By contrast, the functions whose names start with ‘delete-’ normally do not save text for yanking (though they can still be undone); these are deletion functions.

ほとんどのkillコマンドは、主にインタラクティブな使用を意図しており、ここでは説明しません。ここで説明するのは、そのようなコマンドの記述に使用されるために提供される関数です。テキストをkillするために、これらのカを使用できます。Lisp関数の内部的な目的のためにテキストの削除を要するときは、killリング内のコンテンツに影響を与えないように、通常は削除関数を使用するべきでしょう。テキストの削除を参照してください。

killされたテキストは、後のyank用にkillリング(kill ring)内に保存されます。これは、直前のkillだけでなく直近のkillのいくつかを保持するリストです。yankがそれをサイクル順に要素をもつリストとして扱うので、これを“リング(ring)”と称しています。このリストは変数kill-ringに保持されており、リスト用の通常関数で操作可能です。このセクションで説明する、これをリングとして扱うために特化された関数も存在します。

Some people think this use of the word “kill” is unfortunate, since it refers to operations that specifically do not destroy the entities killed. This is in sharp contrast to ordinary life, in which death is permanent and killed entities do not come back to life. Therefore, other metaphors have been proposed. For example, the term “cut ring” makes sense to people who, in pre-computer days, used scissors and paste to cut up and rearrange manuscripts. However, it would be difficult to change the terminology now.

32.8.1 killリングの概念

killリングは、リスト内でもっとも最近にkillされたテキストが先頭になるように、killされたテキストを記録します。たとえば、短いkillリングは以下のようになるでしょう:

("some text" "a different piece of text" "even older text")

このリストのエントリー長がkill-ring-maxに達すると、新たなエントリー追加により最後のエントリーが自動的に削除されます。

killコマンドが他のコマンドと混ざり合っているときは、各killコマンドはkillリング内に新たなエントリーを作成します。連続する複数のkillコマンドは単一のkillリングエントリーを構成します。これは1つの単位としてyankされます。2つ目以降の連続するkillコマンドは、最初のkillにより作成されたエントリーにテキストを追加します。

For yanking, one entry in the kill ring is designated the front of the ring. Some yank commands rotate the ring by designating a different element as the front. But this virtual rotation doesn’t change the list itself—the most recent entry always comes first in the list.

32.8.2 killリングのための関数

kill-region is the usual subroutine for killing text. Any command that calls this function is a kill command (and should probably have ‘kill’ in its name). kill-region puts the newly killed text in a new element at the beginning of the kill ring or adds it to the most recent element. It determines automatically (using last-command) whether the previous command was a kill command, and if so appends the killed text to the most recent entry.

The commands described below can filter the killed text before they save it in the kill ring. They call filter-buffer-substring (see section バッファーのコンテンツを調べる) to perform the filtering. By default, there’s no filtering, but major and minor modes and hook functions can set up filtering, so that text saved in the kill ring is different from what was in the buffer.

Command: kill-region start end &optional region

This function kills the stretch of text between start and end; but if the optional argument region is non-nil, it ignores start and end, and kills the text in the current region instead. The text is deleted but saved in the kill ring, along with its text properties. The value is always nil.

In an interactive call, start and end are point and the mark, and region is always non-nil, so the command always kills the text in the current region.

バッファーまたはテキストが読み取り専用の場合、kill-regionは同じようにkillリングを変更後、バッファーを変更せずにエラーをシグナルする。これは、ユーザーが一連のkillコマンドで、読み取り専用バッファーからkillリングにテキストをコピーするのに有用である。

User Option: kill-read-only-ok: このオプションが非nilなら、バッファーやテキストが読み取り専用でも、kill-regionはエラーをシグナルしない。かわりに、バッファーを変更せずにkillリングを更新して、単にリターンする。

Command: copy-region-as-kill start end &optional region

This function saves the stretch of text between start and end on the kill ring (including text properties), but does not delete the text from the buffer. However, if the optional argument region is non-nil, the function ignores start and end, and saves the current region instead. It always returns nil.

In an interactive call, start and end are point and the mark, and region is always non-nil, so the command always saves the text in the current region.

このコマンドは、後続のkillコマンドが同一のkillリングエントリーに追加しないよう、this-commandにkill-regionをセットしない。

32.8.3 yank

yankとは、killリングからテキストを挿入するものの、単なる挿入ではないことを意味します。yankおよび関連するコマンドは、テキスト挿入前に特別な処理を施すために、insert-for-yankを使用します。

Function: insert-for-yank string: この関数はinsertと同様に機能するが、結果をカレントバッファーに挿入する前に、テキストプロパティyank-handler、同様に変数yank-handled-propertiesおよびyank-excluded-propertiesに応じてstring内のテキストを処理する点が異なる。

Function: insert-buffer-substring-as-yank buf &optional start end: この関数はinsert-buffer-substringと似ているが、yank-handled-propertiesおよびyank-excluded-propertiesに応じてテキストを処理する点が異なる(これはyank-handlerプロパティを処理しないが、いずれにせよバッファー内のテキストでは通常は発生しない)。

文字列の一部またはすべてにテキストプロパティyank-handlerをputした場合、insert-for-yankが文字列を挿入する方法が変更されます。文字列の別の箇所が異なるyank-handlerの値をもつ場合(比較はeqで行われる)、部分文字列はそれぞれ個別に処理されます。プロパティ値は以下の形式からなる1から4要素のリストでなければなりません(2番目以降の要素は省略されるかもしれない):

(function param noexclude undo)

以下は、これらの要素が何を行うかです:

function: functionが非nilなら、insertのかわりに文字列を挿入するために、挿入する文字列を単一の引数として、その関数が呼び出される。
param: 非nilのparamが与えられた場合、それはstring(または処理されるstringの部分文字列)を置き換えるオブジェクトとしてfunction(またはinsert)に渡される。たとえばfunctionがyank-rectangleなら、paramは矩形(rectangle)として挿入されるべき文字列のリストになる。
noexclude: 非nilのnoexcludeが与えられた場合は、挿入される文字列にたいするyank-handled-propertiesおよびyank-excluded-propertiesの通常の動作を無効にする。
undo: 非nilのundoが与えられた場合、それはカレントオブジェクトの挿入をundoするためにyank-popが呼び出す関数である。この関数は、カレントリージョンのstartとendの、2つの引数で呼び出される。functionはyank-undo-functionをセットすることにより、undoの値をオーバーライドできる。

User Option: yank-handled-properties

この変数は、yankされるテキストの状態を処理するスペシャルテキストプロパティを指定する。これは(通常の方法、またはyank-handlerを通じた)テキスト挿入後、yank-excluded-propertiesが効力をもつ前に効果を発揮する。

値は、要素が(prop . fun)であるようなalistであること。alistの各要素は、順番に処理される。挿入されるテキストはテキスト範囲にたいして、テキストプロパティがpropとeqなものがスキャンされる。そのような範囲には、そのプロパティの値、そのテキストの開始と終了の位置という、3つの引数によりfunが呼び出される。

User Option: yank-excluded-properties: この変数の値は、挿入されるテキストから削除するための、プロパティのリストである。デフォルト値には、マウスに応答したりキーバインディングの指定を引き起こすテキストのような、煩わしい結果をもたらすかもしれないプロパティが含まれる。これは、yank-handled-propertiesの後に効果を発揮する。

32.8.4 yankのための関数

このセクションでは、yank用の高レベルなコマンドを説明します。これらのコマンドは主にユーザー用に意図されたものですが、Lispプログラム内での使用にたいしても有用です。yankおよびyank-popはどちらも、変数yank-excluded-propertiesおよびテキストプロパティyank-handlerにしたがいます(yankを参照)。

Command: yank &optional arg

このコマンドは、killリングの先頭にあるテキストを、ポイントの前に挿入する。これはpush-mark(マークを参照)を使用して、そのテキストの先頭にマークをセットする。

argが非nilのリスト(これはユーザーがインタラクティブに数字を指定せずにC-uをタイプ時に発生する)なら、yankは上述のようにテキストを挿入するが、ポイントはyankされたテキストの前、マークはyankされたテキストの後に置かれる。

argが数字なら、yankはarg番目に最近killされたテキスト、すなわちkillリングリストのarg番目の要素を挿入する。この順番は、コマンドの目的にたいして1番目の要素としてみなされる、リスト先頭の要素から巡回的に数えられる。

yankは、それが他のプログラムから提供されるテキストを使用しないかぎり(使用する場合はそのテキストをkillリングにpushする)、killリングのコンテンツを変更しない。しかし、argが非1の整数の場合は、killリングを転回(rotate)してyankされるテキストをリング先頭に置く。

yankはnilをリターンする。

Command: yank-pop &optional arg

このコマンドは、killリング上の正にyankされたばかりのエントリーを、killリングの別エントリーで置き換える。

このコマンドは、yankまたは別のyank-popの直後のみ許される。そのような際、そのリージョンにはyankにより正に挿入されたテキストが含まれる。yank-popはそのテキストを削除して、killされた別のテキスト片をその位置に挿入する。そのテキスト片はすでにkillリング内のどこか別の箇所にあるので、これは削除されたテキストをkillリングに追加しない。しかし、新たにyankされたテキストが先頭になるよう、killリングの転回は行う。

argがnilなら、置換テキストはkillリングの1つ前の要素である。argが数字なら、置換テキストはkillリングのarg個前の要素である。argが負の場合は、より最近のkillが置換される。

killリング内のkillされたエントリーの順序はラップする。すなわちもっとも古いkillの次にもっとも新しいkill、もっとも新しいkillの前はもっとも古いkillとなる。

リターン値は常にnilである。

Variable: yank-undo-function

この変数が非nilの場合、関数yank-popは前のyankまたはyank-popにより挿入されたテキストを削除するために、delete-regionのかわりにこの変数の値を使用する。値は、カレントリージョンの開始と終了という、2つの引数をとる関数でなければならない。

関数insert-for-yankは、テキストプロパティyank-handlerの要素undoに対応して、この変数を自動的にセットする。

32.8.5 低レベルのkillリング

以下の関数および変数は、killリングにたいして低レベルなアクセスを提供しますが、それらはウィンドウシステムの選択(ウィンドウシステムによる選択を参照)との相互作用にも留意するので、Lispプログラム内での使用に関しても依然として有用です。

Function: current-kill n &optional do-not-move

The function current-kill rotates the yanking pointer, which designates the front of the kill ring, by n places (from newer kills to older ones), and returns the text at that place in the ring.

オプションの第2引数do-not-moveが非nilなら、current-killはyankポインターを変更しない。カレントyankポインターから、n個目のkillを単にリターンする。

If n is zero, indicating a request for the latest kill, current-kill calls the value of interprogram-paste-function (documented below) before consulting the kill ring. If that value is a function and calling it returns a string or a list of several strings, current-kill pushes the strings onto the kill ring and returns the first string. It also sets the yanking pointer to point to the kill-ring entry of the first string returned by interprogram-paste-function, regardless of the value of do-not-move. Otherwise, current-kill does not treat a zero value for n specially: it returns the entry pointed at by the yanking pointer and does not move the yanking pointer.

Function: kill-new string &optional replace

This function pushes the text string onto the kill ring and makes the yanking pointer point to it. It discards the oldest entry if appropriate. It also invokes the values of interprogram-paste-function (subject to the user option save-interprogram-paste-before-kill) and interprogram-cut-function (see below).

replaceが非nilなら、kill-newはkillリング上にstringをpushせずに、killリングの1つ目の要素をstringに置き換える。

Function: kill-append string before-p: This function appends the text string to the first entry in the kill ring and makes the yanking pointer point to the combined entry. Normally string goes at the end of the entry, but if before-p is non-nil, it goes at the beginning. This function calls kill-new as a subroutine, thus causing the values of interprogram-cut-function and possibly interprogram-paste-function (see below) to be invoked by extension.

Variable: interprogram-paste-function

この変数は、他のプログラムからkillリングへkillされたテキストを転送する方法を提供する。値はnil、または引数のない関数であること。

If the value is a function, current-kill calls it to get the most recent kill. If the function returns a non-nil value, then that value is used as the most recent kill. If it returns nil, then the front of the kill ring is used.

To facilitate support for window systems that support multiple selections, this function may also return a list of strings. In that case, the first string is used as the most recent kill, and all the other strings are pushed onto the kill ring, for easy access by yank-pop.

この関数の通常の用途は、たとえそれが他アプリケーションに属する選択であっても、もっとも最近のkillとして、ウィンドウシステムのクリップボードからそれを取得することである。しかし、クリップボードのコンテンツがカレントEmacsセッション由来なら、この関数はnilをリターンする筈である。

Variable: interprogram-cut-function

この変数は、ウィンドウシステム使用時に、他のプログラムにkillされたテキストを転送する方法を提供する。値はnil、または1つの引数を要求する関数であること。

値が関数なら、kill-newおよびkill-appendは、killリングの新たな1つ目要素を引数として、それを呼び出す。

この関数の通常の用途は、新たにkillされたテキストを、ウィンドウシステムのクリップボードに配すことである。ウィンドウシステムによる選択を参照のこと。

32.8.6 killリングの内部

変数kill-ringは、文字列リスト形式でkillリングのコンテンツを保持します。もっとも最近のkillが、常にこのリストの先頭になります。

The kill-ring-yank-pointer variable points to a link in the kill ring list, whose CAR is the text to yank next. We say it identifies the front of the ring. Moving kill-ring-yank-pointer to a different link is called rotating the kill ring. We call the kill ring a “ring” because the functions that move the yank pointer wrap around from the end of the list to the beginning, or vice-versa. Rotation of the kill ring is virtual; it does not change the value of kill-ring.

kill-ringおよびkill-ring-yank-pointerはどちらも、通常は値がリストであるようなLisp変数です。kill-ring-yank-pointerの名前にある単語“pointer”は、その変数の目的が次回yankコマンドにより使用されるリストの最初の要素を指すことであるのを示します。

kill-ring-yank-pointerの値は常にkillリングリスト内の1つのリンクとeqです。それが指す要素は、そのリンクのCARです。killリングを変更するkillコマンドも、この変数にkill-ringの値をセットします。その効果は、新たにkillされた先頭になるように、リングを転回することです。

以下は、変数kill-ring-yank-pointerが、killリング("some text" "a different piece of text" "yet older text")内の2番目のエントリーを指すことを表すダイアグラムです。

kill-ring                  ---- kill-ring-yank-pointer
  |                       |
  |                       v
  |     --- ---          --- ---      --- ---
   --> |   |   |------> |   |   |--> |   |   |--> nil
        --- ---          --- ---      --- ---
         |                |            |
         |                |            |
         |                |             -->"yet older text"
         |                |
         |                 --> "a different piece of text"
         |
          --> "some text"

この状態は、C-y(yank)の直後にM-y(yank-pop)を行うことにより発生し得ます。

Variable: kill-ring: この変数は、もっとも最近にkillされたテキストが先頭になるように、killされたテキストのシーケンスのリストを保持する。

Variable: kill-ring-yank-pointer: This variable’s value indicates which element of the kill ring is at the front of the ring for yanking. More precisely, the value is a tail of the value of kill-ring, and its CAR is the kill string that C-y should yank.

User Option: kill-ring-max: この変数の値は、リング終端の要素を破棄する前に、killリングが成長し得る最大長である。kill-ring-maxのデフォルト値は60。

32.9 アンドゥ

ほとんどのバッファーは、バッファーのテキストにたいして行われた変更をundoできるように、すべての変更を記録するundoリスト(undo list)をもちます(undoリストをもたないバッファーとは通常、Emacsがundoを有用とみなさない特殊用途のバッファーである。特に、名前がスペースで始まるバッファーはすべて、undo記録がデフォルトでオフになっている。バッファーの名前を参照されたい)。バッファー内でテキストを変更するすべてのプリミティブは、undoリストの先頭に自動的に要素を追加し、それは変数buffer-undo-listに格納されます。

Variable: buffer-undo-list: このバッファーローカル変数の値は、カレントバッファーのundoリストである。値がtなら、undo情報の記録を無効にする。

以下は、undoリストが保有可能な要素の種類です:

position

この種の要素は、前のポイント値を記録する。この要素をundoすることにより、ポイントはpositionに移動する。通常のカーソル移動はどのような類のundo記録も作成しないが、削除操作はそのコマンド以前にポイントがあった場所を記録するために、このエントリーを使用する。

(beg . end)

この種の要素は、挿入されたテキストを削除する方法を示す。挿入において、そのテキストはバッファー内の範囲begからendを占める。

(text . position)

この種の要素は、削除されたテキストを再度挿入する方法を示す。文字列textは、削除されたテキストそのものである。削除されたテキストを再挿入する位置は(abs position)である。positionが正ならポイントがあったのは削除されたテキストの先頭、それ以外では末尾である。0個以上の(marker . adjustment)要素が、この要素の直後に続く。

(t . time-flag)

この種の要素は、未変更のバッファーが変更されたことを示す。(sec-high sec-low microsec picosec)という形式のtime-flagは、visitされたファイルにたいして、それが以前にvisitまたは保存されたときの更新時刻(modification time)を、current-timeと同じ形式を用いて表す。時刻を参照のこと。time-flagが0ならそのバッファーに対応するファイルがないことを、-1ならvisitされたファイルは以前は存在しなかったことを意味する。primitive-undoは、バッファーを再度未変更とマークするかどうかを判断するために、これらの値を使用(ファイルの状態がtime-flagのそれとマッチする場合のみ未変更とマーク)する。

(nil property value beg . end)

この種の要素は、テキストプロパティの変更を記録する。変更をundoする方法は、以下のようになる:

(put-text-property beg end property value)

(marker . adjustment)

この種の要素は、マーカーmarkerがそれを取り囲むテキストの削除により再配置されて、adjustment文字位置を移動したということを記録する。undoリスト内の前にある要素(text . position)とマーカーの位置が一致する場合、は、この要素をundoすることにより、marker - adjustment文字移動する。

(apply funname . args)

これは拡張可能なundoアイテムであり、引数argsとともにfunnameを呼び出すことによりundoが行われる。

(apply delta beg end funname . args)

これは拡張可能なundoアイテムであり、begからendまでに限定された範囲にたいして、そのバッファーのサイズをdelta文字増加させる変更を記録する。これは、引数argsとともにfunnameを呼び出すことによりundoが行われる。

この種の要素は、それがリージョンと関係するか否かを判断することにより、リージョンに限定されたundoを有効にする。

nil

この要素は境界(boundary)である。2つの境界の間にある要素を変更グループ(change group)と呼び、それぞれの変更グループは通常1つのキーボードコマンドに対応するとともに、undoコマンドは通常、グループを1つの単位として全体をundoを行う。

Function: undo-boundary

この関数は、undoリスト内に境界を配置する。このような境界ごとにundoコマンドは停止し、連続するundoコマンドは、より以前の境界へとundoを行っていく。この関数はnilをリターンする。

この関数を明示的に呼び出すことは、あるコマンドの効果を複数単位に分割するために有用である。たとえばquery-replaceは、ユーザーが個別に置換をundoできるように、それぞれの置換後にundo-boundaryを呼び出している。

Mostly, however, this function is called automatically at an appropriate time.

Function: undo-auto-amalgamate: The editor command loop automatically calls undo-boundary just before executing each key sequence, so that each undo normally undoes the effects of one command. A few exceptional commands are amalgamating: these commands generally cause small changes to buffers, so with these a boundary is inserted only every 20th command, allowing the changes to be undone as a group. By default, the commands self-insert-command, which produces self-inserting input characters (see section ユーザーレベルの挿入コマンド), and delete-char, which deletes characters (see section テキストの削除), are amalgamating. Where a command affects the contents of several buffers, as may happen, for example, when a function on the post-command-hook affects a buffer other than the current-buffer, then undo-boundary will be called in each of the affected buffers.

Variable: undo-auto-current-boundary-timer: Some buffers, such as process buffers, can change even when no commands are executing. In these cases, undo-boundary is normally called periodically by the timer in this variable. Setting this variable to non-nil prevents this behavior.

Variable: undo-in-progress: この変数は通常nilだが、undoコマンドはこれをtにバインドする。これにより、さまざまな種類の変更フックがundoにより呼び出された際、それを告げることが可能になる。

Function: primitive-undo count list

これは、undoリストの要素のundoにたいする基本的な関数である。これはlistの最初のcount要素をundoして、listの残りをリターンする。

primitive-undoはバッファー変更時、そのバッファーのundoリストに要素を追加する。undoコマンドは混乱を避けるために、undo操作シーケンス冒頭にundoリストの値を保存する。その後、undo操作は保存された値の使用および更新を行う。undoにより追加された新たな要素はこの保存値の一部でないので、継続するundoと干渉しない。

この関数は、undo-in-progressをバインドしない。

32.10 アンドゥリストの保守

このセクションでは、与えられたバッファーにたいしてundo情報を有効、および無効にする方法を説明します。undoリストが巨大化しないように、undoリストを切り詰める方法も説明します。

新たに作成されたバッファー内のundo情報記録は、開始とともに通常は有効になります。しかしバッファー名がスペースで始まる場合、undoの記録は初期状態では無効になっています。以下の2つの関数、または自身でbuffer-undo-listをセットすることにより、undo記録の有効、または無効化を明示的に行うことができます。

Command: buffer-enable-undo &optional buffer-or-name

このコマンドは、以降の変更をundo可能にするよう、バッファーbuffer-or-nameのundo情報記録を有効にする。引数が与えられない場合は、カレントバッファーを使用する。そのバッファー内のundo記録がすでに有効なら、この関数は何も行わない。リターン値はnil。

インタラクティブな呼び出しでは、buffer-or-nameはカレントバッファーであり、他のバッファーを指定することはできない。

Command: buffer-disable-undo &optional buffer-or-name

この関数はbuffer-or-nameのundoリストを破棄して、それ以上のundo情報記録を無効にする。結果として、以前の変更および以降のすべての変更にたいするそれ以上のundoは不可能になる。buffer-or-nameのundoリストがすでに無効なら、この関数に効果はない。

インタラクティブな呼び出しでは、BUFFER-OR-NAMEはカレントバッファーとなる。他のバッファーを指定することはできない。リターン値はnil。

As editing continues, undo lists get longer and longer. To prevent them from using up all available memory space, garbage collection trims them back to size limits you can set. (For this purpose, the size of an undo list measures the cons cells that make up the list, plus the strings of deleted text.) Three variables control the range of acceptable sizes: undo-limit, undo-strong-limit and undo-outer-limit. In these variables, size is counted as the number of bytes occupied, which includes both saved text and other data.

User Option: undo-limit: これは、許容できるundoリストサイズのソフトリミットである。このサイズを超過した箇所の変更グループは、最新の変更グループ1つが保持される。

User Option: undo-strong-limit: これは、undoリストの許容できるサイズの上限である。このサイズを超過する箇所の変更グループは(その他すべてのより古い変更グループとともに)自身を破棄する。1つ例外があり、undo-outer-limitを超過した場合は、最新の変更グループだけが破棄される。

User Option: undo-outer-limit: ガベージコレクション時にカレントコマンドのundo情報がこの制限を超過したら、Emacsはその情報を破棄して、警告を表示する。これはメモリーオーバーフローを防ぐための、最後の回避用リミットである。

User Option: undo-ask-before-discard

この変数が非nilなら、undo情報のundo-outer-limit超過時、Emacsはその情報を破棄するかどうかを、エコーエリアで尋ねる。デフォルト値はnilで、これは自動的な破棄を意味する。

このオプションは、主にデバッグを意図している。これを尋ねる際、ガベージコレクションは抑制されており、もしユーザーがその問にたいして答えるのをあまりに長くかかるなら、Emacsがメモリーリークを起こすかもしれないことを意味する。

32.11 fill

フィル(fill: 充填)とは、指定された最大幅付近(ただし超えず)に、(行ブレークを移動することにより)行の長さを調整することを意味します。加えて、複数行を位置揃え(justify)することもできます。位置揃えとは、スペースを挿入して左および/または右マージンを正確に整列させることを意味します。その幅は、変数fill-columnにより制御されます。読みやすくするために、行の長さは70列程度を超えないようにするべきです。

テキストの挿入とともに自動的にテキストをフィルするAuto Fillモードを使用できますが、既存テキストの変更では不適切にフィルされたままになるかもしれません。その場合は、テキストを明示的にフィルしなければなりません。

このセクションのコマンドのほとんどは、有意な値をリターンしません。フィルを行うすべての関数は、カレント左マージン、カレント右マージン、カレント位置揃えスタイルに留意します(fillのマージンを参照)。カレント位置揃えスタイルがnoneの場合、フィル関数は実際には何も行いません。

フィル関数のいくつかは、引数justifyをもちます。これが非nilなら、それは何らかの類の位置揃えを要求します。特定の位置揃えスタイルを要求するためにleft、right、full、centerを指定できます。これがtなら、それはそのテキスト部分にたいしてカレント位置揃えスタイルを使用することを意味します(以下のcurrent-justificationを参照)。その他すべての値は、fullとして扱われます。

インタラクティブにフィル関数を呼び出す際、プレフィクス引数の使用はjustifyにたいして暗に値fullを指定します。

Command: fill-paragraph &optional justify region

このコマンドは、ポイント位置、またはその後のパラグラフ(paragraph: 段落)をフィルする。justifyが非nilなら、同様に各行が位置揃えされる。これはパラグラフ境界を探すために、通常のパラグラフ移動コマンドを使用する。Paragraphs in The GNU Emacs Manualを参照のこと。

もしregionが非nilで、Transient Markモードが有効かつマークがアクティブなら、このコマンドはカレントパラグラフのみフィルするかわりに、リージョン内すべてのパラグラフをフィルするために、コマンドfill-regionを呼び出す。このコマンドがインタラクティブに呼び出されたとき、regionはtである。

Command: fill-region start end &optional justify nosqueeze to-eop

このコマンドは、startからendのリージョン内のすべてのパラグラフをフィルする。justifyが非nilなら、同様に位置揃えも行う。

nosqueezeが非nilなら、それは行ブレーク以外の空白文字を残すことを意味する。to-eopが非nilの場合、それはパラグラフ終端(以下のuse-hard-newlinesが有効なら次のhard改行)までのフィルを維持することを意味する

変数paragraph-separateは、パラグラフを分割する方法を制御する。編集で使用される標準的な正規表現を参照のこと。

Command: fill-individual-paragraphs start end &optional justify citation-regexp

このコマンドは、リージョン内の各パラグラフを、それの固有なフィルプレフィクスに応じてフィルする。したがって、パラグラフの行がスペースでインデントされている場合、フィルされたパラグラフは同じ様式でインデントされた状態に保たれるだろう。

最初の2つの引数startとendは、フィルするリージョンの先頭と終端である。3つ目の引数justify、4つ目の引数citation-regexpはオプションである。justifyが非nilなら、そのパラグラフはフィルと同様に位置揃えもされる。citation-regexpが非nilなら、それはこの関数がメールメッセージを処理しているので、ヘッダーラインをフィルするべきではないことを意味する。citation-regexpが文字列の場合、それは正規表現として扱われる。それが行の先頭にマッチすれば、その行は引用マーカー(citation marker)として扱われる。

fill-individual-paragraphsは通常、インデントの変更を新たなパラグラフの開始とみなす。fill-individual-varying-indentが非nilの場合は、セパレーターラインだけがパラグラフを分割する。その場合は、最初の行からさらにインデントが追加されたパラグラフを処理することが可能になる。

User Option: fill-individual-varying-indent: この変数は、上述のようにfill-individual-paragraphsの動作を変更する。

Command: fill-region-as-paragraph start end &optional justify nosqueeze squeeze-after

このコマンドは、テキストのリージョンを1つのパラグラフとみなして、それをフィルする。そのリージョンが多数のパラグラフから構成されていたら、パラグラフ間の空行は削除される。justifyが非nilなら、フィルとともに位置揃えも行う。

nosqueezeが非nilなら、それは改行以外の空白に手を加えずに残すことを意味する。squeeze-afterが非nilの場合、それはリージョン内の位置を指定し、その位置より前にあるスペースについては標準化を行わないことを意味する。

Adaptive Fillモードでは、このコマンドはフィルプレフィクスを選択するために、デフォルトでfill-context-prefixを呼び出す。Adaptive Fillモードを参照のこと。

Command: justify-current-line &optional how eop nosqueeze

このコマンドは、その行が正確にfill-columnで終わるように、単語間にスペースを挿入する。リターン値はnil。

The argument how, if non-nil specifies explicitly the style of justification. It can be left, right, full, center, or none. If it is t, that means to follow specified justification style (see current-justification, below). nil means to do full justification.

eopが非nilなら、それはcurrent-justificationがfull位置揃えを指定する場合にleft位置揃えだけを行うことを意味する。これは、パラグラフ最終行にたいして使用される。パラグラフ全体がfull位置揃えだったとしても、最終行はfull位置揃えであるべきではない。

nosqueezeが非nilなら、それは内部のスペースを変更しないことを意味する。

User Option: default-justification: この変数の値は、位置揃えに使用するスタイルをテキストプロパティで指定しないテキストにたいするスタイルを指定する。可能な値はleft、right、full、center、またはnone。デフォルト値はleftである。

Function: current-justification

この関数は、ポイント周辺のフィルに使用するための、適正な位置揃えスタイルをリターンする。

This returns the value of the justification text property at point, or the variable default-justification if there is no such text property. However, it returns nil rather than none to mean “don’t justify”.

User Option: sentence-end-double-space: この変数が非nilの場合、ピリオドの後の単一のスペースをセンテンスの終わりとみなさず、フィル関数はそのような箇所でのラインブレークを行わない。

User Option: sentence-end-without-period: この変数が非nilなら、ピリオドなしでセンテンスは終了できる。これはたとえば、ピリオドなしの2連スペースでセンテンスが終わるタイ語な土に使用される。

User Option: sentence-end-without-space: この変数が非nilなら、それは後にスペースをともなうことなくセンテンスを終了させ得る文字列であること。

User Option: fill-separate-heterogeneous-words-with-space: If this variable is non-nil, two words of different kind (e.g., English and CJK) will be separated with a space when concatenating one that is in the end of a line and the other that is in the beginning of the next line for filling.

Variable: fill-paragraph-function

この変数は、パラグラフのフィルをオーバーライドする手段を提供する。この値が非nilなら、fill-paragraphはその処理を行うためにその関数を呼び出す。その関数が非nil値をリターンした場合、fill-paragraphは処理が終了したとみなして、即座にその値をリターンする。

この機能の通常の用途は、プログラミング言語のモードにおいてコメントをフィルすることである。通常の方法でその関数がパラグラフをフィルする必要がある場合は、以下のようにそれを行うことができる:

(let ((fill-paragraph-function nil))
  (fill-paragraph arg))

Variable: fill-forward-paragraph-function: この変数は、fill-regionやfill-paragraphのようなフィル関数が、次のパラグラフへ前方に移動する方法を、オーバーライドするための手段を提供する。値は、移動するパラグラフの数nを唯一の引数として呼び出される関数で、nと実際に移動したパラグラフ数の差をリターンするべきである。この変数のデフォルト値はforward-paragraph。Paragraphs in The GNU Emacs Manualを参照のこと。

Variable: use-hard-newlines: If this variable is non-nil, the filling functions do not delete newlines that have the hard text property. These hard newlines act as paragraph separators. See Hard and Soft Newlines in The GNU Emacs Manual.

32.12 fillのマージン

User Option: fill-prefix

このバッファーローカル変数が非nilなら、それは通常のテキスト行の先頭に出現そ、それらのテキスト行をフィルする際には無視されるべきテキスト文字列を指定する。そのフィルプレフィクスで始まらない行はパラグラフの開始とみなされ、フィルプレフィクスで始まる行は、その後にスペースが追加される。フィルプレフィクスで始まりその後に追加のスペースがない行は、フィル可能な通常のテキスト行である。結果となるフィル済みの行も、フィルプレフィクスで開始される。

もしあれば、フィルプレフィクスは左マージンのスペースの後になる。

User Option: fill-column

このバッファーローカル変数は、フィルされる行の最大幅を指定する。値は列数を表す整数であること。Auto Fillモード(オートfillを参照)を含む、フィル、位置揃え、センタリングを行うすべてのコマンドが、この変数の影響を受ける。

実際の問題として、他の人が読むためのテキストを記述する場合は、fill-columnを70より大きくするべきではない。これにしたがわない場合、人が快適に読むには行が長くなり過ぎ、それは下手に記述されたテキストに見えてしまうだろう。

fill-columnのデフォルト値は70である。

Command: set-left-margin from to margin: これは、fromからtoのテキストのleft-marginプロパティに、値marginをセットする。Auto Fillモードが有効なら、このコマンドは新たなマージンにフィットするよう、リージョンの再フィルも行う。

Command: set-right-margin from to margin: これは、fromからtoのテキストのright-marginプロパティに、値marginをセットする。Auto Fillモードが有効なら、このコマンドは新たなマージンにフィットするよう、リージョンの再フィルも行う。

Function: current-left-margin: この関数は、ポイント周辺をフィルするために使用する、適切な左マージン値をリターンする。値はカレント行開始文字のleft-marginプロパティの値(なければ0)と、変数left-marginの値の合計。

Function: current-fill-column: この関数は、ポイント周辺のテキストをフィルするために使用する、適切なフィル列値をリターンする。値は、変数fill-columnからポイント後の文字のright-marginプロパティの値を減じた値。

Command: move-to-left-margin &optional n force

この関数は、カレント行の左マージンにポイントを移動する。移動先の列は、関数current-left-marginにより決定される。引数nが非nilなら、move-to-left-marginはまずn行前方に移動する。

forceが非nilの場合、それは行のインデントが左マージン値とマッチしなければ、インデントを修正するよう指定する。

Function: delete-to-left-margin &optional from to: この関数は、fromからtoの間のテキストから、左マージンのインデントを取り除く。削除するインデントの量は、current-left-marginを呼び出すことにより決定される。この関数が、非空白文字を削除することはない。fromとtoが省略された場合のデフォルトは、そのバッファー全体である。

Function: indent-to-left-margin: この関数は、カレント行の先頭のインデントを、変数left-marginに指定された値に調整する(これにより空白文字の挿入や削除が起こるかもしれない)。Paragraph-Indent Textモード内の変数indent-line-functionの値は、この関数である。

User Option: left-margin: This variable specifies the base left margin column. In Fundamental mode, RET indents to this column. This variable automatically becomes buffer-local when set in any fashion.

User Option: fill-nobreak-predicate: この変数はメジャーモードにたいして、特定の箇所で行ブレークしないよう指定する手段を提供する。値は関数のリストであること。フィルがバッファー内の特定箇所で行ブレークすると判断されるときは常に、その箇所にポイントを置いた状態で、これらの関数を引数なしで呼び出す。これらの関数のいずれ可が非nilをリターンした場合は、その行のその箇所では行ブレークしない。

32.13 Adaptive Fillモード

Adaptive Fillモードが有効なとき、Emacsは事前定義された値を使用するのではなく、フィルされる各パラグラフのテキストから自動的に、フィルプレフィクスを決定します。このフィルプレフィクスはフィルの間、fillとオートfillで説明されているように、そのパラグラフの2行目以降の行頭に挿入されます。

User Option: adaptive-fill-mode: この変数が非nilなら、Adaptive Fillモードは有効である。デフォルトはt。

Function: fill-context-prefix from to

この関数は、Adaptive Fillモードの肝を実装する。これはfromからto、通常はパラグラフの開始から終了にあるテキストにもとづいて、フィルプレフィクスを選択する。これは、以下で説明する変数にもとづき、そのパラグラフの最初の2行を調べることにより、これを行う。

この関数は通常、文字列としてフィルプレフィクスをリターンする。しかしこれを行う前に、この関数はそのプレフィクスで始まる行がパラグラフの開始とは見えないだろうか、最終チェックを行う(以降では特に明記しない)。これが発生した場合、この関数はかわりにnilをリターンすることにより、異常を通知する。

以下が、fill-context-prefixが行う詳細である:

1行目からフィルプレフィクス候補を取得するために、(もしあれば)まずadaptive-fill-function内の関数、次にadaptive-fill-regexp(以下参照)の正規表現を試みる。これらの非nilの最初の結果、いずれもnilなら空文字列が1行目の候補となる。
そのパラグラフが1行だけなら、関数は見つかったプレフィクス候補の妥当性をテストする。その後、この関数はそれが妥当ならその候補を、それ以外はスペース文字列をリターンする(以下のadaptive-fill-first-line-regexpの説明を参照)。
すでにそのパラグラフが2行以上なら、この関数は次に1行目にたいして行なったのとまったく同じ方法で、2行目でプレフィクス候補を探す。見つからなければnilをリターンする。
ここで、この関数は発見的手法により2つのプレフィクス候補を比較する。2行目の候補の非空白文字の並びが1行目の候補と同じなら、この関数は2行目の候補をリターンする。それ以外では、2つの候補に共通するもっとも長い先頭の部分文字列(これは空文字列かもしれない)をリターンする。

User Option: adaptive-fill-regexp

Adaptive Fillモードは、(もしあれば)行の左マージン空白文字の後から開始されるテキストにたいして、この正規表現をマッチする。マッチする文字列が、その行のフィルプレフィクス候補である。

デフォルト値は、空白文字と特定の句読点文字が混在した文字列にマッチする。

User Option: adaptive-fill-first-line-regexp

Used only in one-line paragraphs, this regular expression acts as an additional check of the validity of the one available candidate fill prefix: the candidate must match this regular expression, or match comment-start-skip. If it doesn’t, fill-context-prefix replaces the candidate with a string of spaces of the same width as it.

この変数のデフォルト値は "\\`[ \t]*\\'"で、これは空白文字列だけにマッチする。このデフォルトの効果は、1行パラグラフで見つかったフィルプレフィクスが、常に純粋な空白文字となるよう強制することである。

User Option: adaptive-fill-function: You can specify more complex ways of choosing a fill prefix automatically by setting this variable to a function. The function is called with point after the left margin (if any) of a line, and it must preserve point. It should return either that line’s fill prefix or nil, meaning it has failed to determine a prefix.

32.14 オートfill

Auto Fill mode is a minor mode that fills lines automatically as text is inserted. See Auto Fill in The GNU Emacs Manual. This section describes some variables used by Auto Fill mode. For a description of functions that you can call explicitly to fill and justify existing text, see fill.

Auto Fillモードでは、テキスの一部を再フィルするために、マージンや位置揃えを変更する関数も利用できます。fillのマージンを参照してください。

Variable: auto-fill-function

The value of this buffer-local variable should be a function (of no arguments) to be called after self-inserting a character from the table auto-fill-chars, see below. It may be nil, in which case nothing special is done in that case.

The value of auto-fill-function is do-auto-fill when Auto Fill mode is enabled. That is a function whose sole purpose is to implement the usual strategy for breaking a line.

Variable: normal-auto-fill-function: この変数は、もしAuto Fillがオンのときはauto-fill-functionにたいして使用する関数を指定する。Auto Fillの動作方法を変更するために、メジャーモードはこの変数にバッファーローカル値をセットである。

Variable: auto-fill-chars: 文字が自己挿入された際にauto-fill-functionを呼び出す文字(ほとんどの言語環境においてはスペースと改行)からなる文字テーブル。

User Option: comment-auto-fill-only-comments: This variable, if non-nil, means to fill lines automatically within comments only. More precisely, this means that if a comment syntax was defined for the current buffer, then self-inserting a character outside of a comment will not call auto-fill-function.

32.15 テキストのソート

このセクションで説明するソート関数はすべて、バッファー内のテキストを再配置し。これはリスト要素を再配置するsort関数とは対照的です(see section リストを再配置する関数)。これらの関数がリターンする値に意味はありません。

Function: sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun predicate

この関数はバッファーをレコードに細分してそれらをソートする、一般的なテキストソートルーチンである。このセクションのコマンドのほとんどは、この関数を使用する。

sort-subrが機能する方法を理解するためには、バッファーのアクセス可能範囲をソートレコード(sort records)と呼ばれる、分離された断片に分割すると考えればよい。レコードは連続、あるいは非連続かもしれないが、オーバーラップしてはならない。各ソートレコードの一部(全体かもしれない)は、ソートキーとして指定される。これらソートキーによるソートにより、レコードは再配置される。

通常、レコードはソートキー昇順で再配置される。sort-subrの1つ目の引数reverseが非nilなら、レコードはソートキー降順にソートされて再配置される。

sort-subrにたいする以下の4つの引数は、ソートレコード間でポイントを移動するために呼び出される。これらはsort-subr内で頻繁に呼び出される。

nextrecfunは、レコード終端のポイントで呼び出される。この関数は次のレコードの先頭にポイントを移動する。sort-subrが呼び出された際は、ポイント位置が1つ目のレコードの開始とみなされる。したがってsort-subrを呼び出す前は、通常はそのバッファーの先頭にポイントを移動すること。
この関数はバッファー終端にポイントを残すことにより、それ以上のソートレコードがないことを示すことができるできる。
endrecfunは、レコード内にあるポイントで呼び出される。これはレコード終端にポイントを移動する。
startkeyfunは、ポイントをレコード先頭からソートキー先頭に移動する。この引数はオプションで、省略された場合はレコード全体がソートキーとなる。もし与えられた場合、その関数はソートキーとして使用する非nil値、またはnil(ソートキーはそのバッファー内のポイント位置から始まることを示す)のいずれかをリターンすること。後者の場合は、ソートキー終端を見るけるためにendkeyfunが呼び出される。
endkeyfunは、ソートキー先頭からソートキー終端にポイントを移動するために呼び出される。引数はオプション。startkeyfunがnilをリターンし、かつこの引数が省略(またはnil)の場合、そのソートキーはレコード終端まで拡張される。startkeyfunが非nil値をリターンした場合、endkeyfunは不要。

引数predicateは、キーを比較するために使用される関数である。キーが数字の場合のデフォルトは<、それ以外ではstring<がデフォルトである。

sort-subrの例として、以下はsort-lines関数の完全な定義である:

;; ドキュメント文字列の冒頭2行は
;; ユーザー閲覧時には1行となることに注意
(defun sort-lines (reverse beg end)
  "リージョン内の行をアルファベット順にソート;\
 引数は降順を意味する
プログラムから呼び出す場合は、以下の3つの引数がある:

REVERSE(非nilは逆順の意)、\
およびBEGとEND(ソートするリージョン)
変数`sort-fold-case'は英字\
大文字小文字の違いが
ソート順に影響するかどうかを決定する"

  (interactive "P\nr")
  (save-excursion
    (save-restriction
      (narrow-to-region beg end)
      (goto-char (point-min))
      (let ((inhibit-field-text-motion t))
        (sort-subr reverse 'forward-line 'end-of-line)))))

ここで、forward-lineは次のレコードの先頭にポイントを移動し、end-of-lineはレコードの終端にポイントを移動する。レコード全体をソートキーとするため、引数startkeyfunおよびendkeyfunは渡していない。

sort-paragraphsはほとんど同じだが、sort-subr呼び出しが以下のようになる:

(sort-subr reverse
           (function
            (lambda ()
              (while (and (not (eobp))
                          (looking-at paragraph-separate))
                (forward-line 1))))
           'forward-paragraph)

ソートレコード内を指す任意のマーカーは、sort-subrリターン後は無意味なマーカー位置のまま取り残される。

User Option: sort-fold-case: この変数が非nilならsort-subr、およびその他のバッファーソート関数は、文字列比較時に大文字小文字の違いを無視する。

Command: sort-regexp-fields reverse record-regexp key-regexp start end

このコマンドは、startからendの間のリージョンを、record-regexpおよびkey-regexpで指定されたようにアルファベット順にソートする。reverseが負の整数なら、逆順にソートする。

アルファベット順のソートとは、2つのソートキーにたいして、それぞれの1つ目の文字同士、2つ目の文字同士といったように比較することにより、キーを比較することを意味する。文字が一致しなければ、それはソートキーが不等なことを意味する。最初の不一致箇所で文字が小さいソートキーが、小さいソートキーとなる。個別の文字は、Emacs文字セット内の文字コードの数値に応じて比較される。

引数record-regexpの値は、バッファーをソートレコードに分割する方法を指定する。各レコードの終端で、この正規表現にたいする検索は完了し、これにマッチするテキストが次のレコードとして採用される。たとえば、改行の前に少なくとも1つの文字がある行にマッチする正規表現‘^.+$’は、そのような行をソートレコードとするだろう。正規表現の構文と意味については、正規表現を参照のこと。

引数key-regexpの値は、各レコードのどの部分がソートキーかを指定する。key-regexpはレコード全体、またはその一部にマッチすることができる。後者の場合、レコードの残りの部分はソート順に影響しないが、レコードが新たな位置に移動される際は、ともに移動される。

引数key-regexpは、record-regexpの部分式(subexpression)、またはその正規表現自体にマッチしたテキストを参照できる。

key-regexpは、以下を指定できる:

‘\digit’: record-regexp内でdigit番目のカッコ‘$...$’でグループ化によりマッチしたテキストがソートキーになる。
‘\&’: レコード全体がソートキーとなる。
正規表現: sort-regexp-fieldsは、そのレコード内で正規表現にたいするマッチを検索する。そのようなマッチがあれば、それがソートキーである。レコード内にkey-regexpにたいするマッチがなければそのレコードは無視され、そのバッファー内でのレコードの位置は変更されないことを意味する(他のレコードがそのレコードを移動するかもしれない)。

たとえば、リージョン内のすべての行にたいして、最初の単語が文字‘f’で始まる行をソートすることを目論む場合は、record-regexpを‘^.*$’、key-regexpを‘\<f\w*\>’にセットするべきである。結果は、以下のような式になるだろう

(sort-regexp-fields nil "^.*$" "\\<f\\w*\\>"
                    (region-beginning)
                    (region-end))

sort-regexp-fieldsをインタラクティブに呼び出した場合は、ミニバッファー内でrecord-regexpとkey-regexpの入力を求める。

Command: sort-lines reverse start end: このコマンドは、startとendの間のリージョン内の行を、アルファベット順にソートする。reverseが非nilなら、逆順にソートする。

Command: sort-paragraphs reverse start end: このコマンドは、startとendの間のリージョン内のパラグラフを、アルファベット順にソートする。reverseが非nilなら、逆順にソートする。

Command: sort-pages reverse start end: このコマンドは、startとendの間のリージョン内のページを、アルファベット順にソートする。reverseが非nilなら、逆順にソートする。

Command: sort-fields field start end: このコマンドは、startとendの間のリージョン内の行にたいして、各行のfield番目のフィールドをアルファベット順に比較することに、行をソートする。fieldは空白文字により区切られ、1から数えられる。fieldが負なら、行の終端から-field番目のフィールドでソートする。このコマンドは、テーブルのソートに有用である。

Command: sort-numeric-fields field start end

このコマンドは、startとendの間のリージョン内の行にたいして、各行のfield番目のフィールドを数値的に比較することにより、行をソートする。fieldは空白文字により区切られ、1から数えられる。リージョン内の各行の指定されたフィールドは、数字を含んでいなければならない。0で始まる数字は8進数、‘0x’で始まる数字は16進数として扱われる。

fieldが負なら、行の終端から-field番目のフィールドでソートする。このコマンドは、テーブルのソートに有用である。

User Option: sort-numeric-base: この変数は、sort-numeric-fieldsにたいして、数字を解析するための基本基数を指定する。

Command: sort-columns reverse &optional beg end

このコマンドは、begとendの間にある行にたいして、特定の列範囲をアルファベット順に比較することによりソートする。begとendの列位置は、ソートが行われる列範囲にバインドされる。

reverseが非nilなら、逆順にソートする。

このコマンドが普通と異なるのは、位置begを含む行全体と、位置endを含む行全体が、ソートされるリージョンに含まれることである。

タブは指定された列に分割される可能性があるので、sort-columnsはタブを含むテキストを受け付けないことに注意。ソート前にM-x untabifyを使用して、タブをスペースに変換すること。

可能なら、ユーティリティプログラムsortを呼び出すことにより、このコマンドは実際に機能する。

32.16 列を数える

列関数は、文字位置(バッファー先頭から数えた文字数)と、列位置(行先頭から数えたスクリーン文字数)を変換する関数です。

これら列関数は、スクリーン上占める列数に応じて、各文字を数えます。これはコントロール文字はctl-arrowの値に応じて2列、または4列を、タブはtab-widthの値と、タブが始まる列の位置に依存する列数を占めるものとして数えられることを意味します。See section 通常の表示の慣習を参照してください。

列数計算はウィンドウ幅と水平スクロール量を無視します。結果として、列値は任意に大きくなる可能性があります。最初(または左端)の列は0と数えられます。列値は不可視性を別として、オーバーレイとテキストプロパティを無視します。

Function: current-column: この関数は、左マージンを0として、列単位で数えたポイントの水平位置をリターンする。列の位置は、カレント行の開始からポイントまでの間の文字の表示上の表現すべての幅の和である。

Command: move-to-column column &optional force

この関数は、カレント行のcolumnにポイントを移動する。columnの計算には、行の開始からポイントまでの文字の表示上の表現の幅が考慮される。

インタラクティブに呼び出された際は、columnはプレフィクス数引数の値である。columnが整数でなければエラーがシグナルされる。

列columnが、タブのような複数列を占める文字の中間にあるために列を移動することが不可能な場合、ポイントはその文字の終端に移動される。しかしforceが非nil、かつcolumnがタブの中間にあるなら、move-to-columnはタブをスペースに変換して、正確に列columnに移動することができる。それ以外の複数列文字については、それらを分割する手段がないので、force指定に関わらず、異常を引き起こす恐れがある。

その行が列columnに達するほど長くない場合にも、引数forceは効果をもつ。columnがtなら、その列に達するよう行端に空白を追加することを意味する。

リターン値は、実際に移動した列である。

32.17 インデント

インデント関数は、行の先頭にある空白文字の調査、移動、変更に使用されます。行の他の箇所にある空白文字を変更できる関数も、いくつかあります。列およびインデントは、左マージンを0として数えられます。

32.17.1 インデント用のプリミティブ		インデントのカウントと挿入に使用される関数。
32.17.2 メジャーモードが制御するインデント		異なるモード用にインデントをカスタマイズする。
32.17.3 リージョン全体のインデント		リージョン内すべての行のインデント。
32.17.4 前行に相対的なインデント		前の行にもとづきカレント行をインデントする。
32.17.5 Adjustable Tab Stops		調整可能なタイプライター形式のタブストップ。
32.17.6 インデントにもとづくモーションコマンド		最初の非ブランク文字への移動。

32.17.1 インデント用のプリミティブ

このセクションでは、インデントのカウントと挿入に使用されるプリミティブ関数について説明します。以降のセクションの関数は、これらのプリミティブを使用します。関連する関数については、表示されるテキストのサイズを参照してください。

Function: current-indentation: この関数は、カレント行のインデント、すなわち最初の非ブランク文字の水平位置をリターンする。行のコンテンツ全体がブランクなら、それは行終端の水平位置である。

Command: indent-to column &optional minimum

この関数は、ポイントからcolumnに達するまで、タブとスペースでインデントを行う。minimumが指定され、かつそれが非nilなら、たとえcolumnを超えることが要求される場合であっても、少なくともその個数のスペースが挿入される。それ以外では、ポイントがすでにcolumnを超える場合、この関数は何も行わない。値は、挿入されたインデントの終端列である。

挿入される空白文字は、周囲のテキスト(通常は先行するテキストのみ)のテキストプロパティを継承する。テキストプロパティの粘着性を参照のこと。

User Option: indent-tabs-mode: この変数が非nilなら、インデント関数はスペースと同様、タブを挿入でき、それ以外ではスペースだけを挿入できる。この変数をセットすることにより、自動的にカレントバッファー内でバッファーローカルになる。

32.17.2 メジャーモードが制御するインデント

すべてのメジャーモードにとって重要な関数は、編集対象の言語にたいして正しくインデントを行うように、TABキーをカスタマイズします。このセクションでは、TABキーのメカニズムと、それを制御する方法について説明します。このセクションの関数は、予期せぬ値をリターンします。

Command: indent-for-tab-command &optional rigid

これはほとんどの編集用モードで、TABにバインドされるコマンドである。これの通常の動作はカレント行のインデントだが、かわりにタブ文字の挿入や、リージョンのインデントを行うこともできる。

これは以下のことを行う:

まずTransient Markモードが有効か、そしてリージョンがアクティブかどうかをチェックする。もしそうなら、リージョン内のテキストすべてをインデントするためにindent-regionを呼び出す(リージョン全体のインデントを参照)。
それ以外なら、indent-line-function内のインデント関数がindent-to-left-marginの場合、または変数tab-always-indentが挿入する文字としてタブ文字を指定する場合(以下参照)は、タブ文字を挿入する。
それ以外なら、カレント行をインデントする。これはindent-line-function内の関数を呼び出すことにより行われる。その行がすでにインデント済みで、かつtab-always-indentの値がcomplete(以下参照)なら、ポイント位置のテキストの補完を試みる。

rigidが非nil(インタラクティブな場合はプレフィクス引数)の場合、このコマンドが行をインデントした後、あるいはタブを挿入後、新たなインデントを反映するために、このコマンドはカレント行先頭にあるバランスされた式全体も厳正にインデントする。この引数は、コマンドがリージョンをインデントする場合は無視される。

Variable: indent-line-function: この変数の値はカレント行をインデントするためにindent-for-tab-command、およびその他種々のインデントコマンドにより使用される関数である。これは通常メジャーモードにより割り当てられ、たとえばLispモードはこれをlisp-indent-line、Cモードはc-indent-line、のようにセットする。デフォルト値はindent-relative。コードの自動インデントを参照のこと。

Command: indent-according-to-mode: このコマンドは、カレントのメジャーモードに適した方法でカレント行をインデントするために、indent-line-function内の関数を呼び出す。

Command: newline-and-indent: この関数は改行を挿入後、メジャーモードに応じて新たな行(挿入した改行の次の行)をインデントする。これはindent-according-to-modeを呼び出すことによりインデントを行う。

Command: reindent-then-newline-and-indent: このコマンドは、カレント行の再インデント、ポイント位置への改行の挿入、その後新たな行(挿入した改行の次の行)のインデントを行う。これはindent-according-to-modeを呼び出すことにより、両方の行をインデントする。

User Option: tab-always-indent: この変数は、TAB(indent-for-tab-command)コマンドの挙動のカスタマイズに使用できる。値がt(デフォルト)なら、コマンドは通常カレント行だけをインデントする。値がnilなら、コマンドはポイントが左マージン、またはその行のインデント内ににあるときのみ、カレント行をインデントし、それ以外はタブ文字を挿入する。値がcompleteなら、コマンドはまずカレント行のインデントを試み、その行がすでにインデント済みならポイント位置のテキストを補完するためにcompletion-at-pointを呼び出す(通常バッファーでの補完を参照)。

Some major modes need to support embedded regions of text whose syntax belongs to a different major mode. Examples include literate programming source files that combine documentation and snippets of source code, Yacc/Bison programs that include snippets of Python or JS code, etc. To correctly indent the embedded chunks, the primary mode needs to delegate the indentation to another mode’s indentation engine (e.g., call js-indent-line for JS code or python-indent-line for Python), while providing it with some context to guide the indentation. Major modes, for their part, should avoid calling widen in their indentation code and obey prog-first-column.

Variable: prog-indentation-context

This variable, when non-nil, holds the indentation context for the sub-mode’s indentation engine provided by the superior major mode. The value should be a list of the form (first-column . rest. The members of the list have the following meaning:

first-column: The column to be used for top-level constructs. This replaces the default value of the top-level column used by the sub-mode, usually zero.
rest: This value is currently unused.

The following convenience function should be used by major mode’s indentation engine in support of invocations as sub-modes of another major mode.

Function: prog-first-column: Call this function instead of using a literal value (usually, zero) of the column number for indenting top-level program constructs. The function’s value is the column number to use for top-level constructs. When no superior mode is in effect, this function returns zero.

32.17.3 リージョン全体のインデント

このセクションでは、リージョン内すべての行をインデントするコマンドを説明します。これらは予期せぬ値をリターンします。

Command: indent-region start end &optional to-column

このコマンドは、start(含む)からend(含まず)で始まる非ブランク行すべてをインデントする。to-columnがnilなら、indent-regionはカレントモードのインデント関数、すなわちindent-line-functionの値を呼び出すことにより、非ブランク行すべてをインデントする。

to-columnが非nilなら、それはインデントの列数を指定する整数であること。その場合、この関数は空白文字を追加もしくは削除することにより、正確にその量のインデントを各行に与える。

フィルプレフィクスがある場合、indent-regionはそのフィルプレフィクスで開始されるように、各行をインデントする。

Variable: indent-region-function

この変数の値は、ショートカットとしてindent-regionにより使用されるかもしれない関数である。その関数はリージョンの開始と終了という、2つの引数をとること。その関数はリージョンの行を1行ずつインデントするときと同じような結果を生成するようにデザインするべきだが、おそらくより高速になるであろう。

値がnilならショートカットは存在せず、indent-regionは実際に1行ずつ機能する。

ショートカット関数は、indent-line-functionが関数定義先頭をスキャンしなければならない、CモードやLispモードのようなモードに有用で、それを各行に適用するためには行数の2乗に比例する時間を要するだろう。ショートカットは各行のインデントとともに移動してスキャン情報を更新でき、それは線形時間である。行を個別にインデントするのが高速なモードでは、ショートカットの必要性はない。

引数to-columnが非nilのindent-regionでは意味は異なり、この変数は使用しない。

Command: indent-rigidly start end count

This function indents all lines starting between start (inclusive) and end (exclusive) sideways by count columns. This preserves the shape of the affected region, moving it as a rigid unit.

これはインデントされていないテキストリージョンのインデントだけでなく、フォーマット済みコードのリージョンにたいするインデントにも有用である。たとえばcountが3なら、このコマンドは指定されたリージョン内で始まるすべての行のインデントに3を追加する。

プレフィクス引数なしでインタラクティブに呼び出された場合、このコマンドはインデントを厳密に調整するために、Transient Markモードを呼び出す。Indentation Commands in The GNU Emacs Manualを参照のこと。

Command: indent-code-rigidly start end columns &optional nochange-regexp

これはindent-rigidlyと似ているが、文字列やコメントで始まる行を変更しない点が異なる。

加えて、(nochange-regexpが非nilの場合)nochange-regexpが行先頭にマッチすれば、その行を変更しない。

32.17.4 前行に相対的なインデント

このセクションでは、前の行のコンテンツにもとづいてカレント行をインデントする、コマンドを2つ説明します。

Command: indent-relative &optional unindented-ok

このコマンドは、前の非ブランク行の次のインデントポイント(indent point)と同じ列に拡張されるように、ポイント位置に空白文字を挿入する。インデントポイントとは、後に空白文字をともなった非空白文字である。次のインデントポイントは、ポイントのカレント列より大きい、最初のインデントポイントになる。たとえばポイントがテキスト行の最初の非ブランク文字の下と左にある場合、空白文字を挿入してその列に移動する。

前の非ブランク行に次のインデントポイントがない(列の位置が十分大きくない)場合は、(unindented-okが非nilなら)何もしないか、あるいはtab-to-tab-stopを呼び出す。したがって、ポイントが短いテキスト行の最後の列の下と右にある場合、このコマンドは通常は空白文字を挿入することにより、次のタブストップにポイントを移動する。

indent-relativeのリターン値は予測できない。

以下の例では、ポイントは2行目の先頭にある:

            This line is indented twelve spaces.
∗The quick brown fox jumped.

式(indent-relative nil)の評価により、以下が生成される:

            This line is indented twelve spaces.
            ∗The quick brown fox jumped.

次の例では、ポイントは‘jumped’の‘m’と‘p’の間にある:

            This line is indented twelve spaces.
The quick brown fox jum∗ped.

式(indent-relative nil)の評価により、以下が生成される:

            This line is indented twelve spaces.
The quick brown fox jum  ∗ped.

Command: indent-relative-maybe

このコマンドは、引数unindented-okにtを指定してindent-relativeを呼び出すことにより、前の非ブランク行に倣ってカレント行をインデントする。リターン値は予測できない。

カレント列より先のインデントポイントが前の非ブランク行に存在しなければ、このコマンドは何もしない。

32.17.5 Adjustable Tab Stops

This section explains the mechanism for user-specified tab stops and the mechanisms that use and set them. The name “tab stops” is used because the feature is similar to that of the tab stops on a typewriter. The feature works by inserting an appropriate number of spaces and tab characters to reach the next tab stop column; it does not affect the display of tab characters in the buffer (see section 通常の表示の慣習). Note that the TAB character as input uses this tab stop feature only in a few major modes, such as Text mode. See Tab Stops in The GNU Emacs Manual.

Command: tab-to-tab-stop: このコマンドは、tab-stop-listにより定義される次のタブストップ列まで、ポイント前にスペースまたはタブを挿入する。

User Option: tab-stop-list

この変数は、tab-to-tab-stopにより使用されるタブストップ列を定義する。これはnil、もしくは増加(均等に増加する必要はない)していく整数のリストであること。このリストは暗黙に、最後の要素と最後から2番目の要素の間隔(またはリストの要素が2未満ならtab-width)を繰り返すことにより、無限に拡張される。値nilは、列tab-widthごとにタブストップすることを意味する。

インタラクティブにタブストップの位置を編集するには、M-x edit-tab-stopsを使用すればよい。

32.17.6 インデントにもとづくモーションコマンド

以下のコマンドは主にインタラクティブに使用され、テキスト内のインデントにもとづいて動作します。

Command: back-to-indentation: このコマンドは、カレント行(ポイントのある行のこと)の最初の非空白文字にポイントを移動する。リターン値はnil。

Command: backward-to-indentation &optional arg: このコマンドは、後方へarg行ポイントを移動した後に、その行の最初の非ブランク文字にポイントを移動する。リターン値はnil。argが省略またはnilのときのデフォルトは1。

Command: forward-to-indentation &optional arg: このコマンドは、前方へarg行ポイントを移動した後に、その行の最初の非ブランク文字にポイントを移動する。リターン値はnil。argが省略またはnilのときのデフォルトは1。

32.18 大文字小文字の変更

ここで説明する大文字小文字変換コマンドは、カレントバッファー内のテキストに作用します。文字列と文字の大文字小文字変換コマンドはLispでの大文字小文字変換、大文字または小文字に変換する文字や、その変換方法のカスタマイズはcaseテーブルを参照してください。

Command: capitalize-region start end

この関数はstartとendで定義されるリージョン内のすべての単語をcapitalizeする。capitalizeとは、各単語の最初の文字を大文字、残りの文字を小文字に変換することを意味する。この関数はnilをリターンする。

リージョンのいずれかの端が単語の中間にある場合は、リージョン内にある部分を単語全体として扱う。

インタラクティブにcapitalize-regionが呼び出された際は、startとendはポイントとマークになり、小さいほうが先になる。

---------- Buffer: foo ----------
This is the contents of the 5th foo.
---------- Buffer: foo ----------

(capitalize-region 1 37)
⇒ nil

---------- Buffer: foo ----------
This Is The Contents Of The 5th Foo.
---------- Buffer: foo ----------

Command: downcase-region start end

この関数は、startとendで定義されるリージョン内のすべての英文字を小文字に変換する。この関数はnilをリターンする。

インタラクティブにdowncase-regionが呼び出された際は、startとendはポイントとマークになり、小さいほうが先になる。

Command: upcase-region start end

この関数は、startとendで定義されるリージョン内のすべての英文字を大文字に変換する。この関数はnilをリターンする。

インタラクティブにupcase-regionが呼び出された際は、startとendはポイントとマークになり、小さいほうが先になる。

Command: capitalize-word count

この関数は、ポイントの後のcount単語をcapitalizeして、変換後その後にポイントを移動する。capitalizeとは、各単語の先頭を大文字、残りを小文字に変換することを意味する。countが負なら、この関数は前の-count単語をcapitalizeするが、ポイントは移動しない。値はnil。

ポイントが単語の中間にある場合、ポイントの前にある単語部分は、前方に移動する際は無視される。そして残りの部分が単語全体として扱われる。

インタラクティブにcapitalize-wordが呼び出された際は、countに数プレフィクス引数がセットされる。

Command: downcase-word count

この関数は、ポイントの後のcount単語を小文字に変換して、変換後その後にポイントを移動する。countが負なら、この関数は前の-count単語を小文字に変換するが、ポイントは移動しない。値はnil。

インタラクティブにdowncase-wordが呼び出された際は、countに数プレフィクス引数がセットされる。

Command: upcase-word count

この関数は、ポイントの後のcount単語を大文字に変換して、変換後その後にポイントを移動する。countが負なら、この関数は前の-count単語を小文字に変換するが、ポイントは移動しない。値はnil。

インタラクティブにupcase-wordが呼び出された際は、countに数プレフィクス引数がセットされる。

32.19 テキストのプロパティ

バッファーや文字列内の各文字位置は、シンボルにおけるプロパティリスト(プロパティリストを参照)のように、テキストプロパティリスト(text property list)をもつことができます。特定の位置の特定の文字に属するプロパティ、たとえばこのセンテンス先頭の文字‘T’(訳注: 翻訳前のセンテンスは"The properties belong to a ..."で始まる)、または‘foo’の最初の‘o’など、もし同じ文字が異なる2箇所に存在する場合、2つの文字は一般的に異なるプロパティをもちます。

それぞれのプロパティには、名前と値があります。どちらも任意のLispオブジェクトをもつことができますが、名前は通常はシンボルです。典型的には、それぞれのプロパティ名シンボルは、特定の目的のために使用されます。たとえば、テキストプロパティfaceは、文字を表示するためのフェイスを指定します(特殊な意味をもつプロパティを参照)。名前を指定してそれに対応する値を尋ねるのが、このプロパティリストにアクセスするための通常の方法です。

ある文字がcategoryプロパティをもつ場合は、それをその文字のプロパティカテゴリー(property category)と呼びます。これはシンボルであるべきです。そのシンボルのプロパティは、その文字のプロパティにたいしてデフォルトとしての役割をもちます。

文字列とバッファーの間でテキストをコピーには、文字とともにそのプロパティが保持されます。これにはsubstring、insert、buffer-substringのようなさまざまな関数が含まれます。

32.19.1 テキストプロパティを調べる		単一の文字のプロパティを調べる。
32.19.2 テキストプロパティの変更		テキスト範囲のプロパティをセットする。
32.19.3 テキストプロパティの検索関数		プロパティが値を変更する場所の検索。
32.19.4 特殊な意味をもつプロパティ		特別な意味をもつ特定のプロパティ。
32.19.5 フォーマットされたテキストプロパティ		テキストのフォーマットを表すプロパティ。
32.19.6 テキストプロパティの粘着性		挿入されたテキストが隣接するテキストからプロパティを取得する方法。
32.19.7 テキストプロパティのlazyな計算		テキストが調べられる際のみ、ものぐさな方法でテキストプロパティを計算する。
32.19.8 クリック可能なテキストの定義		テキストプロパティを使用して、テキストリージョンがクリック時に何か行うようにする。
32.19.9 フィールドの定義と使用		バッファー内にフィールドを定義する`field`プロパティ。
32.19.10 なぜテキストプロパティはインターバルではないのか		テキストプロパティがLispから可視なテキスト間隔をもたない理由。

32.19.1 テキストプロパティを調べる

テキストプロパティを調べるもっともシンプルな方法は、特定の文字の特定のプロパティの値を尋ねる方法です。これを行うには、get-text-propertyを使用します。ある文字のプロパティリスト全体を取得するには、text-properties-atを使用します。複数の文字のプロパティを一度に調べる関数については、テキストプロパティの検索関数を参照してください。

以下の関数は、文字列とバッファーの両方を処理します。バッファー内の位置は1から始まりますが、文字列内の位置は0から始まることに留意してください。

Function: get-text-property pos prop &optional object

この関数は、object(バッファーまたは文字列)内の位置posの後にある文字のプロパティpropの値をリターンする。引数objectはオプションで、デフォルトはカレントバッファー。

厳密な意味でpropプロパティが存在しないが、その文字がシンボルであるようなプロパティカテゴリーをもつなら、get-text-propertyはそのシンボルのpropプロパティをリターンする。

Function: get-char-property position prop &optional object

この関数はget-text-propertyと似ているが、まずオーバーレイをチェックして、次にテキストプロパティをチェックする点が異なる。オーバーレイを参照のこと。

引数objectは文字列、バッファー、あるいはウィンドウかもしれない。ウィンドウならそのウィンドウ内に表示されているバッファーのテキストプロパティとオーバーレイが使用されるが、そのウィンドウにたいしてアクティブなオーバーレイだけが考慮される。objectがバッファーなら、そのバッファー内のオーバーレイがまず優先順に考慮され、その後にテキストプロパティが考慮される。objectが文字列の場合？文字列は決してオーバーレイをもたないので、テキストプロパティだけが考慮される。

Function: get-pos-property position prop &optional object: This function is like get-char-property, except that it pays attention to properties’ stickiness and overlays’ advancement settings instead of the property of the character at (i.e., right after) position.

Function: get-char-property-and-overlay position prop &optional object

これはget-char-propertyと似ているが、そのプロパティ値が由来するオーバーレイについて追加情報を与える点が異なる。

その値はCARがプロパティ値であるようなコンスセルで、同じ引数によりget-char-propertyがリターンするであろう値と同じである。CDRはそのプロパティが見つかった箇所のオーバーレイ、またはテキストプロパティとして見つかった場合や見つからなかった場合はnilである。

positionがobjectの終端なら、CARとCDRの値はどちらもnilになる。

Variable: char-property-alias-alist: この変数は、プロパティ名と代替となるプロパティ名リストをマップするalistを保持する。文字があるプロパティにたいして直接値を指定しなければ、順に代替プロパティ名が調べられ、最初の非nil値が使用される。この変数はdefault-text-propertiesより優先され、この変数よりcategoryプロパティが優先される。

Function: text-properties-at position &optional object: この関数は、文字列またはバッファーobject内の位置positionにある文字のプロパティリスト全体をリターンする。objectがnilなら、デフォルトはカレントバッファーとなる。

Variable: default-text-properties

この変数は、テキストプロパティにたいしてデフォルト値を与えるプロパティリストを保持する。あるプロパティにたいして文字が直接、あるいはカテゴリーシンボルまたはchar-property-alias-alistを通じて値を指定しないときは常に、このリストに格納された値がかわりに使用される。以下は例である:

(setq default-text-properties '(foo 69)
      char-property-alias-alist nil)
;; 文字1は自身のプロパティをもたない
(set-text-properties 1 2 nil)
;; 取得される値はデフォルト値である
(get-text-property 1 'foo)
     ⇒ 69

32.19.2 テキストプロパティの変更

プロパティを変更するプリミティブは、バッファーまたは文字列内の指定されたテキスト範囲に適用されます。関数set-text-properties(セクションの最後を参照)は、その範囲内のテキストのプロパティリスト全体をセットします。名前を指定することにより特定のプロパティだけを追加、変更、削除するのにも、より有用です。

テキストプロパティはバッファー(または文字列)のコンテンツの一部とみなされ、かつスクリーン上でのバッファーの見栄えに影響を与えることができるので、バッファー内のテキストプロパティの変更はすべて、バッファーを変更済みとマークします。バッファーテキストプロパティの変更も、アンドゥできます(アンドゥを参照)。バッファー内の位置は1から始まりますが、文字列内の位置は0から始まります。

Function: put-text-property start end prop value &optional object: この関数は、文字列またはバッファーobject内のstartとendの間のテキストにたいして、プロパティpropにvalueをセットする。objectがnilなら、デフォルトはカレントバッファーである。

Function: add-text-properties start end props &optional object

この関数は、文字列またはバッファーobject内のstartとendの間のテキストにたいして、テキストプロパティを追加またはオーバーライドする。objectがnilなら、デフォルトはカレントバッファーである。

引数propsは、追加するプロパティを指定する。これはプロパティリストの形式(プロパティリストを参照)、つまりプロパティ名と対応する値が交互に出現するような要素を含むリストであること。

関数が実際に何らかのプロパティの値を変更したらt、それ以外(propsがnil、またはプロパティの値がテキスト内のプロパティの値と一致している場合)はnilがリターン値となる。

たとえば、以下はテキストの範囲にcommentとfaceのプロパティをセットする例である:

(add-text-properties start end
                     '(comment t face highlight))

Function: remove-text-properties start end props &optional object

この関数は、文字列またはバッファーobject内のstartとendの間のテキストから、指定されたテキストプロパティを削除する。objectがnilなら、デフォルトはカレントバッファーとなる。

引数propsは、削除するプロパティを指定する。これはプロパティリストの形式(プロパティリストを参照)、つまりプロパティ名と対応する値が交互に出現するような要素を含むリストであること。しかし問題となるのは名前であり、付随する値は無視される。たとえばfaceプロパティを削除するには、以下のようにすればよい。

(remove-text-properties start end '(face nil))

関数が実際に何らかのプロパティの値を変更したらt、それ以外(propsがnil、または指定されたテキスト内にそれらのプロパティをもつ文字がない場合)はnilがリターン値となる。

特定のテキストからすべてのテキストプロパティを削除するには、新たなプロパティリストにnilを指定して、set-text-propertiesを使用すればよい。

Function: remove-list-of-text-properties start end list-of-properties &optional object: remove-text-propertiesと同様だが、list-of-propertiesがプロパティ名と値が交互になったリストではなく、プロパティ名だけのリストである点が異なる。

Function: set-text-properties start end props &optional object

この関数は、文字列またはバッファーobject内のstartからendの間のテキストにたいするテキストプロパティリストを、完全に置き換える。objectがnilなら、デフォルトはカレントバッファーとなる。

引数propsは新たなプロパティリスト。これはプロパティメジャーと対応する値が交互となるような要素のリストであること。

set-text-propertiesのリターン後は、指定された範囲内のすべての文字は、等しいプロパティをもつ。

propsがnilなら、指定されたテキスト範囲からすべてのプロパティを取り除く効果がある。以下は例である:

(set-text-properties start end nil)

この関数のリターン値を信用してはならない。

Function: add-face-text-property start end face &optional appendp object

この関数はstartとendの間のテキストのテキストプロパティfaceにフェイスfaceを追加するよう動作する。faceはフェイス名もしくはanonymousフェイス(anonymous face: 無名フェイス)のような、faceプロパティ(特殊な意味をもつプロパティを参照)にたいして有効な値であること(フェイスを参照)。

If any text in the region already has a non-nil face property, those face(s) are retained. This function sets the face property to a list of faces, with face as the first element (by default) and the pre-existing faces as the remaining elements. If the optional argument appendp is non-nil, face is appended to the end of the list instead. Note that in a face list, the first occurring value for each attribute takes precedence.

For example, the following code would assign an italicized green face to the text between start and end:

(add-face-text-property start end 'italic)
(add-face-text-property start end '(:foreground "red"))
(add-face-text-property start end '(:foreground "green"))

オプション引数objectが非nilなら、それはカレントバッファーではなく、動作するバッファーまたは文字列を指定する。objectが文字列なら、startとendは0基準で文字列内をインデックス付けする。

文字列にテキストプロパティを付するもっとも簡単な方法は、propertizeです:

Function: propertize string &rest properties

この関数は、テキストプロパティpropertiesを追加した、stringのコピーをリターンする。これらのプロパティは、リターンされる文字列内のすべての文字に適用される。以下は、faceプロパティとmouse-faceプロパティとともに文字列を構築する例である:

(propertize "foo" 'face 'italic
            'mouse-face 'bold-italic)
     ⇒ #("foo" 0 3 (mouse-face bold-italic face italic))

文字列のさまざまな部分に異なるプロパティをputするんは、それぞれの部分をpropertizeで構築して、concatでそれらを結合すればよい:

(concat
 (propertize "foo" 'face 'italic
             'mouse-face 'bold-italic)
 " and "
 (propertize "bar" 'face 'italic
             'mouse-face 'bold-italic))
     ⇒ #("foo and bar"
                 0 3 (face italic mouse-face bold-italic)
                 3 8 nil
                 8 11 (face italic mouse-face bold-italic))

プロパティではなくバッファーからテキストをコピーする関数buffer-substring-no-propertiesについては、バッファーのコンテンツを調べるを参照してください。

If you wish to add or remove text properties to a buffer without marking the buffer as modified, you can wrap the calls above in the with-silent-modifications macro.

32.19.3 テキストプロパティの検索関数

テキストプロパティの通常の使用では、ほとんどの場合は複数または多くの連続する文字が、同じ値のプロパティをもちます。文字を1つずつ調べるプログラムを記述するよりも、同じプロパティ値をもつテキスト塊(chunks of text)を処理するほうが、より高速です。

以下は、これを行うことに使用できる関数です。これらは、プロパティ値の比較にeqを使用します。すべての関数において、objectのデフォルトはカレントバッファーです。

より良いパフォーマンスのためには、特に単一のプロパティを検索する関数においては、limit引数の使用が重要です。そうしないと、興味のあるプロパティが変化しない場合に、バッファー終端までのスキャンに長い時間を要するでしょう。

これらの関数はポイントを移動しません。そのかわりに位置(またはnil)をリターンします。ポイントは常に文字と文字の間にあることを思い出してください。これらの関数によりリターンされる位置は、異なるプロパティをもつ、2つの文字の間にあります。

Function: next-property-change pos &optional object limit

この関数は文字列またはバッファーobject内の位置posから、何らかのテキストプロパティの変化が見つかるまで、テキストを前方にスキャンして、変化のあった位置をリターンする。言い換えると、posの直後の文字とプロパティが等しくない、posの先にある最初の文字の位置をリターンする。

limitが非nilなら、スキャンは位置limitで停止する。そのポイントより前にプロパティが変化しなければ、この関数はlimitをリターンする。

プロパティがobject終端まで変化せず、かつlimitがnilなら、値はnilとなる。値が非nilなら、それはpos以上の位置である。limitがposと等しいときのみ、値はposになる。

以下は、すべてのプロパティが定数であるようなテキスト塊によりバッファーをスキャンする方法の例である:

(while (not (eobp))
  (let ((plist (text-properties-at (point)))
        (next-change
         (or (next-property-change (point) (current-buffer))
             (point-max))))
    ポイントからnext-changeへテキストを処理…
    (goto-char next-change)))

Function: previous-property-change pos &optional object limit: これはnext-property-changeと似ているが、posから前方ではなく後方にスキャンする点が異なる。値が非nilなら、それはpos以下の位置である。limitとposが等しい場合のみ、posをリターンする。

Function: next-single-property-change pos prop &optional object limit

この関数はプロパティprop内の変化についてテキストをスキャンして、変化があった位置をリターンする。このスキャンは、文字列またはバッファーobject内の位置posから、前方に行われる。言い換えると、posの直後の文字とプロパティpropが等しくない、posの先にある最初の文字の位置をリターンする。

limitが非nilなら、スキャンは位置limitで終了する。そのポイントより前にプロパティの変化がなければ、next-single-property-changeはlimitをリターンする。

Function: previous-single-property-change pos prop &optional object limit: これはnext-single-property-changeと似ているが、posから前方ではなく後方にスキャンする点が異なる。値が非nilなら、それはpos以下の位置である。limitとposが等しい場合のみ、posをリターンする。

Function: next-char-property-change pos &optional limit: next-property-changeと似ているが、これはテキストプロパティと同様オーバーレイも考慮し、バッファー終端より前に変化が見つからなければ、nilではなくバッファー位置の最大をリターンする点が異なる(この点ではnext-property-changeよりも対応するオーバーレイ関数next-overlay-changeと似る)。この関数はカレントバッファーだけを処理するので、objectオペランドは存在しない。これは、いずれかの種類のプロパティが変化した、次のアドレスをリターンする。

Function: previous-char-property-change pos &optional limit: これはnext-char-property-changeと似ているが、posから前方ではなく後方へスキャンすること、および変化が見つからなければバッファー位置の最小をリターンする点が異なる。

Function: next-single-char-property-change pos prop &optional object limit: next-single-property-changeと似ているが、これはテキストプロパティと同様オーバーレイも考慮し、object終端より前に変化が見つからなければ、nilではなくobject内の有効な位置の最大をリターンする点が異なる。next-char-property-changeと異なり、、この関数はobjectオペランドをもつ。objectが非バッファーなら、テキストプロパティだけが考慮される。

Function: previous-single-char-property-change pos prop &optional object limit: これはnext-single-char-property-changeと似ているが、posから前方ではなく後方へスキャンすること、および変化が見つからなければobject内の有効な位置の最小をリターンする点が異なる。

Function: text-property-any start end prop value &optional object

この関数は、startとendの間に少なくともプロパティpropに値valueをもつ文字が1つあれば、非nilをリターンする。より正確には、これはそのような最初の文字の位置をリターンし、それ以外はnilをリターンする。

5つ目のオプション引数objectは、スキャンする文字列またはバッファーを指定する。位置はobjectにたいして相対的である。objectのデフォルトは、カレントバッファー。

Function: text-property-not-all start end prop value &optional object

この関数は、startとendの間に少なくともプロパティpropに値valueをもたない文字が1つあれば、非nilをリターンする。より正確には、これはそのような最初の文字の位置をリターンし、それ以外はnilをリターンする。

32.19.4 特殊な意味をもつプロパティ

以下は、ビルトインで特別な意味をもつテキストプロパティ名のテーブルです。以降のセクションでは、フィルとプロパティ継承を制御する特別なプロパティ名をいくつか追加でリストしています。これ以外のすべての名前は特別な意味をもたず、自由に使用できます。

注意: プロパティcomposition、display、invisible、intangibleはすべてのEmacsコマンドの後に、好ましい箇所にポイントを移動させることもできます。コマンド後のポイントの調整を参照してください。

category

ある文字がcategoryプロパティをもつ場合は、それをその文字のプロパティカテゴリー(property category)と呼びます。これはシンボルであること。このシンボルのプロパティは、その文字のプロパティのデフォルトとしての役割をもつ。

face

faceプロパティはその文字の外観を制御する(フェイスを参照)。このプロパティの値は、以下をとることができる:

フェイス名(シンボルか文字列)。
anonymousフェイス: (keyword value …)形式のプロパティリスト。keywordはそれぞれフェイス属性名で、valueはその属性の値。
フェイスのリスト。各リスト要素はフェイス名かanonymousフェイスであること。これはリストされた各フェイス属性を集計したフェイスを指定する。このリスト内で最初にあるフェイスが、より高い優先度をもつ。
(foreground-color . color-name)または(background-color . color-name)形式のコンスセル。これは(:foreground color-name)や(:background color-name)と同じようにフォアグラウンドまたはバックグラウンドを指定する。この形式は後方互換のためだけにサポートされており、無視するべきである。

Font Lockモード(Font Lockモードを参照)はほとんどのバッファーにおいて、コンテキストにもとづき文字のfaceプロパティを動的に更新することにより機能する。

add-face-text-property関数は、このプロパティをセットする便利な手段を提供する。テキストプロパティの変更を参照のこと。

font-lock-face

このプロパティは、Font Lockモードが配下にあるテキストに適用すべきfaceプロパティにたいして値を指定する。これはFont Lockモードに使用されるフォント表示手法の1つであり、独自のハイライトを実装する特別なモードにたいして有用である。事前計算されたフォント化を参照のこと。Font Lockモードが無効なら、font-lock-faceに効果はない。

mouse-face

このプロパティは、文字上または近傍にマウスがあるとき、faceのかわりに使用される。この目的にたいして“近傍”とは、文字間のすべてのテキスト、およびマウスが同じmouse-faceプロパティの値をもつことを意味する。

Emacsはテキストサイズ(:height、:weight、:slant)を変更するmouse-faceプロパティ由来の属性すべてを無視する。これらの属性は、ハイライトされていないテキストと常に等しい。

fontified

This property says whether the text is ready for display. If nil, Emacs’s redisplay routine calls the functions in fontification-functions (see section フェイスの自動割り当て) to prepare this part of the buffer before it is displayed. It is used internally by the just-in-time font locking code.

display

このプロパティは、テキストが表示される方法を変更する、さまざまな機能をアクティブ化する。たとえばこれによりテキスト外観を縦長(taller)または縦短(short)したり、高く(higher)または低く(lower)、太く(wider)または細く(narrower)したり、あるいはイメージに置き換えることができる。displayプロパティを参照のこと。

help-echo

If text has a string as its help-echo property, then when you move the mouse onto that text, Emacs displays that string in the echo area, or in the tooltip window (see section Tooltips).

help-echoプロパティの値が関数なら、その関数はwindow、object、posの3つの引数で呼び出され、ヘルプ文字列、または存在しない場合はnilをリターンすること。1つ目の引数windowは、そのヘルプが見つかったウィンドウである。2つ目の引数objectは、help-echoプロパティをもつバッファー、オーバーレイ、または文字列である。pos引数は以下のとおり:

objectがバッファーなら、posはそのバッファー内の位置。
objectがオーバーレイなら、そのオーバーレイはhelp-echoプロパティをもち、posはそのオーバーレイのバッファー内の位置である。
objectが文字列(オーバーレイ文字列、またはdisplayプロパティにより表示された文字列)なら、posはその文字列内の位置。

help-echoプロパティの値が関数と文字列のいずれでもない場合、それはヘルプ文字列を得るために評価される。

変数show-help-functionをセットすることにより、ヘルプテキストが表示される方法を変更できる(Help displayを参照)。

この機能はモードライン内、およびその他のアクティブテキストにたいして使用される。

keymap

keymapプロパティは、コマンドにたいして追加のキーマップを指定する。このキーマップを適用する際は、マイナーモードキーマップおよびバッファーのローカルマップの前に、キー照合にこのマップが使用される。アクティブなキーマップを参照のこと。プロパティ値がシンボルなら、そのシンボルの関数定義がキーマップとして使用される。

ポイントの前の文字のプロパティの値は、それが非nilでrear-stickyであり、かつポイントの後の文字のプロパティ値が非nilでfront-stickyなら適用される(マウスクリックではポイント位置のかわりにクリック位置が使用される)。

local-map

このプロパティはkeymapと同じように機能するが、これはそのバッファーのローカルマップのかわりに使用するキーマップを指定する点が異なる。ほとんど(もしかするとすべて)の目的にたいしては、keymapを使用するほうが良いだろう。

syntax-table

syntax-tableプロパティは、特定の文字にたいして、どのシンタックステーブルがオーバーライドするかを告げる。構文プロパティを参照のこと。

read-only

ある文字がプロパティread-onlyをもつなら、その文字の変更は許可されない。これを行おうとするすべてのコマンドは、text-read-onlyエラーを受け取る。プロパティの値が文字列なら、その文字列がエラーメッセージとして使用される。

read-only文字に隣接する箇所への挿入は、そこに通常のテキストの行うことがstickinessによるread-onlyプロパティを継承するなら、エラーとなる。つまりstickinessを制御することにより、read-onlyテキストに隣接する挿入の権限を制御することができる。テキストプロパティの粘着性を参照のこと。

プロパティ変更はバッファー変更とみなされるので、特別なトリック(inhibit-read-onlyを非nilにバインドしてからプロパティを削除する)を知らないかぎり、read-onlyプロパティを取り除くことは不可能である。読み取り専用のバッファーを参照のこと。

inhibit-read-only

Characters that have the property inhibit-read-only can be edited even in read-only buffers. See section 読み取り専用のバッファー.

invisible

非nilのinvisibleプロパティにより、スクリーン上で文字を不可視にできる。詳細は不可視のテキストを参照されたい。

intangible

連続する文字のグループが非nilの等しいintangibleプロパティをもつなら、それらの文字の間にポイントを置くことは不可能である。そのグループ内に前方へポイントの移動を試みると、ポイントは実際にはそのグループの終端に移動する。そのグループ内に後方へポイントの移動を試みると、ポイントは実際にはそのグループの先頭に移動する。

連続する文字のグループが非nilの等しくないintangibleプロパティをもつなら、それらの文字は個別のグループに属し、各グループは上述のように別のグループとして扱われる。

When the variable inhibit-point-motion-hooks is non-nil (as it is by default), the intangible property is ignored.

Beware: this property operates at a very low level, and affects a lot of code in unexpected ways. So use it with extreme caution. A common misuse is to put an intangible property on invisible text, which is actually unnecessary since the command loop will move point outside of the invisible text at the end of each command anyway. See section コマンド後のポイントの調整. For these reasons, this property is obsolete; use the cursor-intangible property instead.

cursor-intangible

When the minor mode cursor-intangible-mode is turned on, point is moved away of any position that has a non-nil cursor-intangible property, just before redisplay happens.

field

同じfieldプロパティをもつ連続する文字は、フィールドを構成する。forward-wordやbeginning-of-lineを含むいくつかの移動関数は、フィールド境界で移動を停止する。フィールドの定義と使用を参照のこと。

cursor

カーソルは通常、カレントバッファー位置にあるオーバーレイ、およびテキストプロパティ文字列の先頭か終端に表示される。文字に非nilのcursorテキストプロパティを与えることにより、それら文字列内の、任意の望む文字にカーソルを置くことができる。加えてcursorプロパティの値が整数なら、それはカーソルがその文字上に表示されるように、オーバーレイまたはdisplayプロパティが始まる位置から数えたバッファーの文字位置の数字を指定する。特に、ある文字のcursorプロパティの値が数字nなら、カーソルは範囲[ovpos..ovpos+n)内の任意のバッファー位置にあるその文字上に表示されるだろう。ここでovposはoverlay-start(オーバーレイの管理を参照)により与えられるオーバーレイ開始位置、またはそのバッファー内でdisplayプロパティが始まる位置である。

言い換えると、文字列の非nil値のcursorプロパティをもつ文字は、カーソルが表示される文字である。このプロパティの値は、カーソルを表示するバッファーの位置を告げる。値が整数なら、オーバーレイまたはdisplayプロパティの始まりからn後ろの位置までの間にポイントがあるとき、カーソルはそこに表示される。値がそれ以外の非nilなら、ポイントがdisplayプロパティの先頭、またはoverlay-startの位置だけに表示される。

When the buffer has many overlay strings (e.g., see section before-string) that conceal some of the buffer text or display properties that are strings, it is a good idea to use the cursor property on these strings to cue the Emacs display about the places where to put the cursor while traversing these strings. This directly communicates to the display engine where the Lisp program wants to put the cursor, or where the user would expect the cursor, when point is located on some buffer position that is “covered” by the display or overlay string.

pointer

これはそのテキストやイメージ上にマウスポインターがあるときの、特定のマウスシェイプを指定する。利用できるポインターシェイプについては、ポインターの形状を参照されたい。

line-spacing

改行は、改行で終わるディスプレイ行の高さを制御するテキストプロパティまたはオーバーレイプロパティline-spacingをもつことができる。このプロパティ値は、デフォルトのフレーム行スペーシングと、バッファーローカル変数line-spacingをオーバーライドする。行の高さを参照のこと。

line-height

改行は、改行で終わるディスプレイ行のトータル高さを制御するテキストプロパティ、またはオーバーレイプロパティline-heightをもつことができる。行の高さを参照のこと。

wrap-prefix

テキストがwrap-prefixプロパティをもつなら、それが定義するプレフィクスは、テキストラッピング(text wrapping: テキスト折り返し)に由来するすべての継続行の先頭に、表示時に追加されるだろう(行が切り詰められた場合、wrap-prefixが使用されることはない)。これは文字列、イメージ(その他のディスプレー仕様を参照)、あるいはディスプレイプロパティ:widthまたは:align-to(スペースの指定を参照)により指定されて空白文字範囲かもしれない。

wrap-prefixはバッファーローカル変数wrap-prefixを使用して、バッファー全体にも指定され得る(が、wrap-prefixテキストプロパティはwrap-prefix変数の値より優先される)。切り詰めを参照のこと。

line-prefix

テキストがline-prefixプロパティをもつなら、それが定義するプレフィクスは表示時に、すべての非継続行の先頭に追加されるだろう。これは文字列、イメージ(その他のディスプレー仕様を参照)、あるいはディスプレイプロパティ:widthまたは:align-to(スペースの指定を参照)により指定されて空白文字範囲かもしれない。

line-prefixはバッファーローカル変数line-prefixを使用して、バッファー全体にも指定され得る(が、line-prefixテキストプロパティはline-prefix変数の値より優先される)。切り詰めを参照のこと。

modification-hooks

ある文字がプロパティmodification-hooksをもつなら、その値は関数のリストであること。その文字の変更により、実際の変更前にそれらの関数すべてが呼び出される。それぞれの関数は、変更されようとするバッファー部分の先頭と終端という、2つの引数を受け取る。特定のmodificationフック関数が、単一のプリミティブにより変更されつつある複数の文字に出現する場合は、その関数が呼び出される回数を予測することはできない。さらに挿入は既存の文字を変更しないので、このフックは文字の削除、他の文字への置換、またはそれらのテキストプロパティ変更時のみ実行されるだろう。

これらの関数がバッファーを変更する場合には、これらのフックを呼び出す内部的メカニズムの混乱を避けるために、それらの関数はそれを行う前後にinhibit-modification-hooksをtにバインドするべきである。

オーバーレイもmodification-hooksプロパティをサポートするが、詳細は若干異なる(オーバーレイのプロパティを参照)。

insert-in-front-hooks

insert-behind-hooks

あるバッファーへの挿入操作は、後続文字のinsert-in-front-hooksプロパティ、および先行文字のinsert-behind-hooksプロパティにリストされる関数も呼び出す。これらの関数は、挿入されるテキストの先頭と終端という、2つの引数を受け取る。関数は、優先される実際の挿入が行われた後に呼び出される。

バッファー内のテキスト変更。に呼び出される他のフックについては、フックの変更も参照されたい。

point-entered

point-left

スペシャルプロパティpoint-enteredおよびpoint-leftは、ポイント移動をリポートするフック関数を記録する。ポイントを移動するたびに、Emacsは以下の2つのプロパティ値を比較する:

古い位置の後の文字のpoint-leftプロパティ。
新しい位置の後の文字のpoint-enteredプロパティ。

これらの2つの値が異なる場合、(nilでなければ)古いポイント値と新しいポイント値という2つの引数とともにそれらそれぞれ呼び出される。

同じ比較は古い位置と新しい位置の前の文字にたいしても行われる。この結果、2つのpoint-left関数(同じ関数かもしれない)、および/または2つのpoint-entered関数(同じ関数かもしれない)が実行される可能性がある。ある場合においては、まずすべてのpoint-left関数が呼び出されて、その後にすべてのpoint-entered関数が呼び出される。

さまざまなバッファー位置にたいして、そこにポイントを移動することなく文字を調べるために、char-afterを使用することができる。実際のポイント値変更だけが、これらのフック関数を呼び出す。

The variable inhibit-point-motion-hooks by default inhibits running the point-left and point-entered hooks, see Inhibit point motion hooks.

These properties are obsolete; please use cursor-sensor-functions instead.

cursor-sensor-functions

This special property records a list of functions that react to cursor motion. Each function in the list is called, just before redisplay, with 3 arguments: the affected window, the previous known position of the cursor, and one of the symbols entered or left, depending on whether the cursor is entering the text that has this property or leaving it. The functions are called only when the minor mode cursor-sensor-mode is turned on.

composition

このテキストプロパティは、文字シーケンスをコンポーネントから構成される単一グリフ(single glyph)として表示するために使用される。しかしこのプロパティの値自身は完全にEmacsの内部的なものであり、たとえばput-text-propertyなどにより直接操作するべくではない。

Variable: inhibit-point-motion-hooks: When this obsolete variable is non-nil, point-left and point-entered hooks are not run, and the intangible property has no effect. Do not set this variable globally; bind it with let. Since the affected properties are obsolete, this variable’s default value is t, to effectively disable them.

Variable: show-help-function: If this variable is non-nil, it specifies a function called to display help strings. These may be help-echo properties, menu help strings (see section 単純なメニューアイテム, see section 拡張メニューアイテム), or tool bar help strings (see section ツールバー). The specified function is called with one argument, the help string to display, which is passed through substitute-command-keys before being given to the function; see ドキュメント内でのキーバインディングの置き換え. Tooltip mode (see Tooltips in The GNU Emacs Manual) provides an example.

32.19.5 フォーマットされたテキストプロパティ

以下のテキストプロパティは、フィルコマンドの挙動に影響を与えます。これらはフォーマットされたテキストを表すために使用されます。fillおよびfillのマージンを参照してください。

hard: 改行文字がこのプロパティをもつなら、それは“hard”改行である。フィルコマンドはhard改行を変更せず、それらを横断して単語を移動しない。しかしこのプロパティは、マイナーモードuse-hard-newlinesが有効な場合のみ影響を与える。Hard and Soft Newlines in The GNU Emacs Manualを参照のこと。
right-margin: このプロパティは、その部分のテキストのフィルにたいして、余分な右マージンを指定する。
left-margin: このプロパティは、その部分のテキストのフィルにたいして、余分な左マージンを指定する。
justification: このプロパティは、その部分のテキストのフィルにたいして、位置揃え(justification)のスタイルを指定する。

32.19.6 テキストプロパティの粘着性

Self-inserting characters, the ones that get inserted into a buffer when the user types them (see section ユーザーレベルの挿入コマンド), normally take on the same properties as the preceding character. This is called inheritance of properties.

By contrast, a Lisp program can do insertion with inheritance or without, depending on the choice of insertion primitive. The ordinary text insertion functions, such as insert, do not inherit any properties. They insert text with precisely the properties of the string being inserted, and no others. This is correct for programs that copy text from one context to another—for example, into or out of the kill ring. To insert with inheritance, use the special primitives described in this section. Self-inserting characters inherit properties because they work using these primitives.

継承つきで挿入を行う際に、どのプロパティがどこから継承されるかは、sticky(スティッキー、粘着する)に依存します。ある文字の後への挿入における、それらのモジノプロパティ継承はrear-sticky(後方スティッキー)です。ある文字の前への挿入における、それらのモジノプロパティ継承はfront-sticky(前方スティッキー)です。これら両側のstickyが、同じプロパティにたいして異なるsticky値をもつ場合は、前の文字の値が優先します。

デフォルトでは、テキストプロパティはfront-stickyではなく、rear-stickyです。したがってデフォルトでは、すべてのプロパティは前の文字から継承し、後の文字からは何も継承しません。

さまざまなテキストプロパティのstickiness(スティッキネス、スティッキー性、粘着性、粘着度)はは、2つのテキストプロパティfront-stickyおよびrear-nonstickyと、変数text-property-default-nonstickyで制御できます。与えられたプロパティにたいして異なるデフォルトを指定するために、この変数を使用できます。テキストの任意の特定部分に特定のプロパティsticky、または非stickyを指定するために、これら2つのテキストプロパティを使用できます。

ある文字のfront-stickyプロパティがtなら、その文字のすべてのプロパティはfront-stickyです。front-stickyプロパティがリストなら、その文字のstickyなプロパティは、名前がそのリスト内にあるプロパティです。たとえばある文字が値が(face read-only)であるようなfront-stickyプロパティをもつなら、その文字の前への挿入ではその文字のfaceプロパティとread-onlyプロパティは継承できますが、他のプロパティはｐ継承できません。

rear-nonstickyは逆の方法で機能します。ほとんどのプロパティはデフォルトでrear-stickyであり、rear-nonstickyプロパティはどのプロパティがrear-stickyではないかを告げますある文字のrear-nostickyプロパティがtなら、その文字のすべてのプロパティはrear-stickyではありません。rear-nostickyプロパティがリストなら、その文字のstickyなプロパティは、名前がそのリスト内にないプロパティです。

Variable: text-property-default-nonsticky

この変数は、さまざまなテキストプロパティのデフォルトのrear-stickinessを定義するalistである。各要素は(property . nonstickiness)という形式をもち、これは特定のテキストプロパティpropertyのstickinessを定義する。

nonstickinessが非nilなら、それはプロパティpropertyがデフォルトでrear-nonstickyであることを意味する。すべてのプロパティはデフォルトでfront-nonstickyなので、これによりpropertyは両方向にたいしてデフォルトでnonstickyになる。

テキストプロパティfront-stickyおよびrear-nonstickyが使用された際には、text-property-default-nonsticky内で指定されたデフォルトのnonstickinessより優先される。

以下はプロパティ継承つきでテキストを挿入する関数です:

Function: insert-and-inherit &rest strings: 関数insertと同じように文字列stringsを挿入するが、隣接するテキストからすべてのstickyなプロパティを継承する。

Function: insert-before-markers-and-inherit &rest strings: 関数insert-before-markersと同じように文字列stringsを挿入するが、隣接するテキストからすべてのstickyなプロパティを継承する。

継承を行わない通常の挿入関数については、テキストの挿入を参照してください。

32.19.7 テキストプロパティのlazyな計算

バッファー内のすべてのテキストにたいしてテキストプロパティを計算するかわりに、何かがテキスト範囲に依存している場合、その際はテキストプロパティを計算するようにアレンジできます。

プロパティとともにバッファーからテキストを抽出するプリミティブは、buffer-substringです。プロパティを調べる前に、この関数はアブノーマルフックbuffer-access-fontify-functionsを実行します。

Variable: buffer-access-fontify-functions: この変数は、テキストプロパティ計算用の関数のリストを保持する。buffer-substringがバッファーの一部のテキストとテキストプロパティをコピーする前に、このリスト内の関数すべてを呼び出す。各関数はアクセスされるバッファー範囲を指定する、2つの引数を受け取る(バッファーは常にカレントバッファーとなる)。

関数buffer-substring-no-propertiesはいずれにせよテキストプロパティを無視するので、これらの関数を呼び出さない。

同じバッファー部分にたいして複数回フック関数が呼び出されるのを防ぐには、変数buffer-access-fontified-propertyを使用できる。

Variable: buffer-access-fontified-property

If this variable’s value is non-nil, it is a symbol which is used as a text property name. A non-nil value for that text property means the other text properties for this character have already been computed.

buffer-substringにたいして指定された範囲内のすべての文字が、このプロパティにたいする値として非nilをもつなら、buffer-substringはbuffer-access-fontify-functionsの関数を呼び出さない。それらの文字がすでに正しいテキストプロパティをもつとみなし、それらがすでに所有するプロパティを単にコピーする。

buffer-access-fontify-functionsの関数にこのプロパティ、同様に他のプロパティを処理対象の文字に追加させるのが、この機能の通常の用途である。この方法では、同じテキストにたいして、それらの関数が何度も呼び出されるのを防ぐことができる。

32.19.8 クリック可能なテキストの定義

クリック可能テキスト(clickable text)とは何らかの結果を生成するために、マウス、またはキーボードコマンドを通じてクリックできるテキストです。多くのメジャーモードがテキスト的なハイパーリンク、略してリンク(link)を実装するために、クリック可能テキストを使用しています。

リンクを挿入および操作するもっとも簡単な方法は、buttonパッケージの使用です。ボタンを参照してください。このセクションではテキストプロパティを使用して、バッファー内に手作業でクリック可能テキストをセットアップする方法を説明します。簡略にするために、クリック可能テキストをリンクと呼ぶことにします。

Implementing a link involves three separate steps: (1) indicating clickability when the mouse moves over the link; (2) making RET or mouse-2 on that link do something; and (3) setting up a follow-link condition so that the link obeys mouse-1-click-follows-link.

クリック可能を示すためには、そのリンクのテキストにmouse-faceプロパティを追加します。すると、以降Emacsはマウスがその上に移動した際にリンクをハイライトするでしょう。加えてhelp-echoテキストプロパティを使用して、ツールチップかエコーエリアメッセージを定義するべきです。特殊な意味をもつプロパティを参照してください。たとえば以下は、Diredがファイル名がクリック可能なことを示す方法です:

 (if (dired-move-to-filename)
     (add-text-properties
       (point)
       (save-excursion
         (dired-move-to-end-of-filename)
         (point))
       '(mouse-face highlight
         help-echo "mouse-2: visit this file in other window")))

To make the link clickable, bind RET and mouse-2 to commands that perform the desired action. Each command should check to see whether it was called on a link, and act accordingly. For instance, Dired’s major mode keymap binds mouse-2 to the following command:

(defun dired-mouse-find-file-other-window (event)
  "In Dired, visit the file or directory name you click on."
  (interactive "e")
  (let ((window (posn-window (event-end event)))
        (pos (posn-point (event-end event)))
        file)
    (if (not (windowp window))
        (error "No file chosen"))
    (with-current-buffer (window-buffer window)
      (goto-char pos)
      (setq file (dired-get-file-for-visit)))
    (if (file-directory-p file)
        (or (and (cdr dired-subdir-alist)
                 (dired-goto-subdir file))
            (progn
              (select-window window)
              (dired-other-window file)))
      (select-window window)
      (find-file-other-window (file-name-sans-versions file t)))))

このコマンドはクリックがどこで発生したかを判断するために、関数posn-windowとposn-point、visitするファイルの判断に関数dired-get-file-for-visitを使用します。

マウスコマンドをメジャーモードキーマップ内でバインドするかわりに、keymapプロパティ(特殊な意味をもつプロパティを参照)を使用して、リンクテキスト内でバインドできます。たとえば:

(let ((map (make-sparse-keymap)))
  (define-key map [mouse-2] 'operate-this-button)
  (put-text-property link-start link-end 'keymap map))

With this method, you can easily define different commands for different links. Furthermore, the global definition of RET and mouse-2 remain available for the rest of the text in the buffer.

The basic Emacs command for clicking on links is mouse-2. However, for compatibility with other graphical applications, Emacs also recognizes mouse-1 clicks on links, provided the user clicks on the link quickly without moving the mouse. This behavior is controlled by the user option mouse-1-click-follows-link. See Mouse References in The GNU Emacs Manual.

To set up the link so that it obeys mouse-1-click-follows-link, you must either (1) apply a follow-link text or overlay property to the link text, or (2) bind the follow-link event to a keymap (which can be a major mode keymap or a local keymap specified via the keymap text property). The value of the follow-link property, or the binding for the follow-link event, acts as a condition for the link action. This condition tells Emacs two things: the circumstances under which a mouse-1 click should be regarded as occurring inside the link, and how to compute an action code that says what to translate the mouse-1 click into. The link action condition can be one of the following:

mouse-face

コンディションがシンボルmouse-faceの場合、その位置に非nilのmouse-faceプロパティがあれば、それはリンク内側の位置である。アクションコードは常にt。

For example, here is how Info mode handles mouse-1:

(define-key Info-mode-map [follow-link] 'mouse-face)

関数

コンディションが関数funcの場合、(func pos)が非nilに評価されれば、位置posはリンクの内側である。funcがリターンする値は、アクションコードとして機能する。

For example, here is how pcvs enables mouse-1 to follow links on file names only:

(define-key map [follow-link]
  (lambda (pos)
    (eq (get-char-property pos 'face) 'cvs-filename-face)))

その他

コンディション値がそれ以外の場合、その位置はリンク内側であり、そのコンディション自体がアクションコードである。(バッファー全体に適用されないように)リンクテキストのテキストプロパティまたはオーバーレイプロパティを通じてコンディションを適用するときのみ、この類のコンディションを指定すべきなのは明確である。

The action code tells mouse-1 how to follow the link:

文字列またはベクター: If the action code is a string or vector, the mouse-1 event is translated into the first element of the string or vector; i.e., the action of the mouse-1 click is the local or global binding of that character or symbol. Thus, if the action code is "foo", mouse-1 translates into f. If it is [foo], mouse-1 translates into foo.
その他: For any other non-nil action code, the mouse-1 event is translated into a mouse-2 event at the same position.

To define mouse-1 to activate a button defined with define-button-type, give the button a follow-link property. The property value should be a link action condition, as described above. See section ボタン. For example, here is how Help mode handles mouse-1:

(define-button-type 'help-xref
  'follow-link t
  'action #'help-button-action)

To define mouse-1 on a widget defined with define-widget, give the widget a :follow-link property. The property value should be a link action condition, as described above. For example, here is how the link widget specifies that a mouse-1 click shall be translated to RET:

(define-widget 'link 'item
  "An embedded link."
  :button-prefix 'widget-link-prefix
  :button-suffix 'widget-link-suffix
  :follow-link "\C-m"
  :help-echo "Follow the link."
  :format "%[%t%]")

Function: mouse-on-link-p pos: この関数は、カレントバッファー内の位置posがリンク上なら、非nilをリターンする。posはevent-startがリターンするようなマウスイベント位置でもよい(マウスイベントへのアクセスを参照)。

32.19.9 フィールドの定義と使用

フィールドとはバッファー内にある連続する文字範囲であり、fieldプロパティ(テキストプロパティかオーバーレイプロパティ)に同じ値(eqで比較)をもつことにより識別されます。このセクションでは、フィールドの操作に利用できるスペシャル関数を説明します。

フィールドは、バッファー位置posで指定します。各フィールドはバッファー位置の範囲を含むと考えて、指定した位置はその位置を含むフィールドを表します。

posの前または後の文字は同じフィールドに属し、どのフィールドがposを含むかという疑問はありません。それらの文字が属するフィールドが、そのフィールドです。posがフィールド境界のときは、それがどのフィールドに属すかは、取り囲む2つの文字のfieldプロパティのstickinessに依存します(テキストプロパティの粘着性を参照)。posに挿入されたテキストからプロパティが継承されたフィールドが、posを含むフィールドです。

posに新たに挿入されたテキストが、いずれの側からもfieldプロパティを継承しない、異常なケースがあります。これは前の文字のfieldプロパティがrear-stickyでなく、後の文字のfieldプロパティがfront-stickyでもない場合に発生します。このケースでは、posは前のフィールドと後のフィールドいずれにも属しません。フィールド関数はそれを、開始と終了がposの空フィールドに属するものとして扱います。

これらすべての関数では、posが省略またはnilの場合は、ポイントの値がデフォルトとして使用されます。ナローイング(narrowing)が効力をもつ場合、posはアクセス可能部分にあるはずです。ナローイングを参照してください。

Function: field-beginning &optional pos escape-from-edge limit

この関数は、posで指定されたフィールドの先頭をリターンする。

posが自身のフィールド先頭にあり、かつescape-from-edgeが非nilなら、pos周辺のfieldプロパティのstickinessに関わらず、リターン値は常にposが終端であるような前のフィールドの先頭になる。

limitが非nilなら、それはバッファーの位置である。そのフィールドの先頭がlimitより前なら、かわりにlimitがリターンされるだろう。

Function: field-end &optional pos escape-from-edge limit

この関数は、posで指定されるフィールドの終端をリターンする。

posが自身のフィールド終端にあり、かつescape-from-edgeが非nilなら、pos周辺のfieldプロパティのstickinessに関わらず、リターン値は常にposが先頭であるような後のフィールドの終端になる。

limitが非nilなら、それはバッファーの位置である。そのフィールドの終端がlimitより後なら、かわりにlimitがリターンされるだろう。

Function: field-string &optional pos: この関数はposで指定されるフィールドのコンテンツを、文字列としてリターンする。

Function: field-string-no-properties &optional pos: この関数は、posで指定されるフィールドのコンテンツを、テキストプロパティを無視して、文字列としてリターンする。

Function: delete-field &optional pos: この関数は、posで指定されるフィールドのテキストを削除する。

Function: constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property

This function constrains new-pos to the field that old-pos belongs to—in other words, it returns the position closest to new-pos that is in the same field as old-pos.

new-posがnilなら、constrain-to-fieldはかわりにポイントの値を使用して、ポイントをリターンすることに加えて、その位置にポイントを移動する。

If old-pos is at the boundary of two fields, then the acceptable final positions depend on the argument escape-from-edge. If escape-from-edge is nil, then new-pos must be in the field whose field property equals what new characters inserted at old-pos would inherit. (This depends on the stickiness of the field property for the characters before and after old-pos.) If escape-from-edge is non-nil, new-pos can be anywhere in the two adjacent fields. Additionally, if two fields are separated by another field with the special value boundary, then any point within this special field is also considered to be on the boundary.

引数なしのC-aコマンドのように、特別な類の位置に後方へ移動して一度そこに留まるには、おそらくescape-from-edgeにたいしてnilを指定するべきであろう。フィールドをチェックする他の移動コマンドにたいしては、おそらくtを渡すべきである。

オプション引数only-in-lineが非nil、かつnew-posを通常の方法により拘束することにより異なる行へ移動するような場合、new-posは非拘束でリターンされる。これはnext-lineやbeginning-of-lineのような行単位の移動コマンドで、それらのコマンドが正しい行へ移動できる場合だけフィールド境界を尊重するようにするために用いられる。

オプション引数inhibit-capture-propertyが非nil、かつold-posがその名前の非nilなプロパティをもつなら、すべてのフィールド境界は無視される。

変数inhibit-field-text-motionを非nil値にバインドすることにより、constrain-to-fieldにすべてのフィールド境界を無視(何者にも拘束されることがない)させることができる。

32.19.10 なぜテキストプロパティはインターバルではないのか

Some editors that support adding attributes to text in the buffer do so by letting the user specify intervals within the text, and adding the properties to the intervals. Those editors permit the user or the programmer to determine where individual intervals start and end. We deliberately provided a different sort of interface in Emacs Lisp to avoid certain paradoxical behavior associated with text modification.

複数のインターバルに細分化することが実際に意味をもつなら、それは特定のプロパティをもつ単一のインターバルのバッファーと、同じテキストをもち、両方が同じプロパティをもつ2つのインターバルに分割されたバッファーを区別できることを意味します。

インターバルを1つだけもつバッファーがあり、その一部をkillすることを考えてみてください。そのそのバッファーに残されるのは1つのインターバルであり、killリング(とundoリスト)内のコピーは別個のインターバルになります。そのkillされたテキストをyankで戻すと、同じプロパティをもつ2つのインターバルを得ることになります。したがって、編集では1つのインターバルと2つのインターバルの違いは保たれません。

Suppose we attempt to fix this problem by coalescing the two intervals when the text is inserted. That works fine if the buffer originally was a single interval. But suppose instead that we have two adjacent intervals with the same properties, and we kill the text of one interval and yank it back. The same interval-coalescence feature that rescues the other case causes trouble in this one: after yanking, we have just one interval. Once again, editing does not preserve the distinction between one interval and two.

インターバルの間の境界上へのテキスト挿入でも、満足できる回答かない問題が発生します。

しかし、“バッファーにあるテキスト位置または文字列位置のプロパティは何?”という形式の問にたいして、編集が一貫した振る舞いをするようアレンジするのは簡単です。そこで、わたしたちはこれらが合理的な唯一の問いであると判断したのです。わたしたちはインターバルの開始と終了の場所を問うような実装をしませんでした。

実際には、明白にインターバル境界であるような箇所では、通常はテキストプロパティ検索関数を使用できます。可能であるならインターバルは常に結合されるとみなすことにより、それらがインターバル境界を探すと考えることができます。テキストプロパティの検索関数を参照してください。

Emacsはプレゼンテーション機能として、明示的なインターバルも提供します。オーバーレイを参照してください。

32.20 文字コードの置き換え

以下の関数は、文字コードにもとづいて、指定されたリージョン内の文字を置き換えます。

Function: subst-char-in-region start end old-char new-char &optional noundo

この関数は、startとendで定義されるカレントバッファーのリージョン内に出現する文字old-charをnew-charに置き換える。

noundoが非nilなら、subst-char-in-regionはundo用に変更を記録せず、バッファーを変更済みとマークしない。これは、古い機能である選択的ディスプレイ(選択的な表示を参照)にとって有用だった。

subst-char-in-regionはポイントを移動せず、nilをリターンする。

---------- Buffer: foo ----------
This is the contents of the buffer before.
---------- Buffer: foo ----------

(subst-char-in-region 1 20 ?i ?X)
     ⇒ nil

---------- Buffer: foo ----------
ThXs Xs the contents of the buffer before.
---------- Buffer: foo ----------

Command: translate-region start end table

この関数は、バッファー内の位置startとendの間の文字にたいして、変換テーブル(translation table)を適用する。

変換テーブルtableは、文字列、または文字テーブルである。(aref table ochar)は、ocharに対応した変換後の文字を与える。tableが文字列なら、tableの長さより大きいコードの文字は、この変更により変更されない。

translate-regionのリターン値は、その変換により実際に変更された文字数である。変換テーブル内でその文字自身にマップされる文字は勘定に入らない。

32.21 レジスター

レジスター(register)とは、Emacs内の編集においてさまざまな異なる種類の値を保持できる、一種の変数のことです。レジスターはそれぞれ、1文字で命名されます。すべてのASCII文字、およびそれらのメタ修飾された変種(ただしC-gは例外)を、レジスターの命名に使用できます。したがって、利用可能なレジスター数は255になります。Emacs Lispでは、レジスターは自身の名前である、その文字により指定されます。

Variable: register-alist

この変数は、要素が(name .contents)という形式のalistである。使用中のEmacsレジスターごとに、通常は1つの要素が存在する。

オブジェクトnameは、レジスターを識別する文字(整数)である。

レジスターのcontentsには、いくつかのタイプがある:

数字: 数字はそれ自身を意味する。insert-registerはレジスター内の数字を探して、その数字を10進数に変換する。
マーカー: マーカーは、ジャンプ先のバッファー位置を表す。
文字列: 文字列の場合は、レジスター内に保存されたテキスト。
矩形(rectangle): 矩形は、文字列のリストを表す。
(window-configuration position): これは1つのフレームにリストアされるウィンドウ構成、およびカレントバッファー内のジャンプ先の位置を表す。
(frame-configuration position): これは、リストア用のフレーム構成、およびカレントバッファー内のジャンプ先の位置である。
(file filename): これはvisitするファイルを表し、この値にジャンプすることによりファイルfilenameをvisitする。
(file-query filename position): これはvisitするファイル、およびそのファイル内の位置を表す。この値にジャンプすることによりファイルfilenameをvisitして、バッファー位置positionに移動する。このタイプの位置をリストアすると、まずユーザーにたいして確認を求める。

このセクションの関数は、特に記さない限り予期せぬ値をリターンします。

Function: get-register reg: この関数はレジスターregのコンテンツ、コンテンツがなければnilをリターンする。

Function: set-register reg value: この関数は、レジスターregのコンテンツにvalueをセットする。レジスターには任意の値をセットできるが、その他のレジスター関数は特定のデータ型を期待する。リターン値はvalue。

Command: view-register reg: このコマンドは、レジスター regに何が含まれているかを表示する。

Command: insert-register reg &optional beforep

このコマンドは、カレントバッファーにレジスターregのコンテンツを挿入する。

Normally, this command puts point before the inserted text, and the mark after it. However, if the optional second argument beforep is non-nil, it puts the mark before and point after.

When called interactively, the command defaults to putting point after text, and a prefix argument inverts this behavior.

レジスターに矩形が含まれる場合、その矩形はポイントの左上隅に挿入される。これはそのテキストがカレント行と、その下に続く行に挿入されることを意味する。

レジスターが保存されたテキスト(文字列)または矩形(リスク)以外の何かを含む場合、現在のところは役に立つようなことは起きない。これは将来変更されるかもしれない。

Function: register-read-with-preview prompt: この関数は、prompt、およびもしかしたら既存レジスターとそのコンテンツをプレビューしてレジスターの名前を読み取り、レジスター名をリターンする。このプレビューは、ユーザーオプションregister-preview-delayとregister-alistがいずれも非nilなら、register-preview-delayで指定された遅延の後に、一時ウィンドウ内に表示される。このプレビューは、ユーザーが(たとえばヘルプ文字のタイプにより)ヘルプを要求した場合も表示される。レジスター名を読み取るスベインタラクティブな関数は、この関数の使用を推奨する。

32.22 テキストの交換

以下の関数は、テキストの一部を置き換えるために使用できます:

Function: transpose-regions start1 end1 start2 end2 &optional leave-markers

This function exchanges two nonoverlapping portions of the buffer (if they overlap, the function signals an error). Arguments start1 and end1 specify the bounds of one portion and arguments start2 and end2 specify the bounds of the other portion.

通常transpose-regionsは、置き換えたテキストにともないマーカーを再配置する。以前は2つの置き換えたテキストのうちの一方の部分に位置していたマーカーは、しの部分とともに移動されるので、それを挟む2つの文字の新たな位置の間に留まることになる。しかしleave-markersが非nilなら、transpose-regionsはこれを行わず、すべてのマーカーを再配置せずに残す。

32.23 Replacing Buffer Text

You can use the following function to replace the text of one buffer with the text of another buffer:

Command: replace-buffer-contents source: This function replaces the accessible portion of the current buffer with the accessible portion of the buffer source. source may either be a buffer object or the name of a buffer. When replace-buffer-contents succeeds, the text of the accessible portion of the current buffer will be equal to the text of the accessible portion of the source buffer. This function attempts to keep point, markers, text properties, and overlays in the current buffer intact. One potential case where this behavior is useful is external code formatting programs: they typically write the reformatted text into a temporary buffer or file, and using delete-region and insert-buffer-substring would destroy these properties. However, the latter combination is typically faster. See section テキストの削除, and テキストの挿入.

32.24 圧縮されたデータの処理

auto-compression-modeが有効なときは、圧縮されたファイルをvisitする際、Emacsはそれを自動的に解凍し、それを変更して保存する際は自動的に再圧縮します。Compressed Files in The GNU Emacs Manualを参照してください。

上記の機能は、外部の実行可能ファイル(例: gzip)を呼び出すことにより機能します。zlibライブラリーを使用したビルトインの解凍サポートつきでEmacsをコンパイルすることもでき、これは外部プログラムの実行に比べて高速です。

Function: zlib-available-p: この関数は、ビルトインzlib解凍が利用可能なら非nilをリターンする。

Function: zlib-decompress-region start end: この関数はビルトインのzlib解凍を使用して、startとendの間のリージョンを解凍する。このリージョンには、gzipかzlibで圧縮されたデータが含まれていなければならない。成功した場合、この関数はリージョンのコンテンツを、解凍されたデータに置き換える。失敗すると、関数はリージョンを未変更のままnilをリターンする。この関数は、ユニバイトバッファーでのみ呼び出すことができる。

32.25 Base 64エンコーディング

Base64コードは、8ビットシーケンスをより長いASCIIグラフィック文字シーケンスにエンコードするために、email内で使用されます。これは、インターネットRFC2045で定義されます¹⁴。このセクションでは、このコードへの変換および逆変換を行う関数について説明します。

Command: base64-encode-region beg end &optional no-line-break

この関数は、begからendのリージョンを、Base64コードに変換する。これはエンコードされたテキストの長さをリターンする。リージョン内の文字がマルチバイトの場合は、エラーをシグナルする(マルチバイトバッファーでは、リージョンにはascii、eight-bit-control、eight-bit-graphicの文字以外は含まれてはならない)。

通常この関数は行が長くなりすぎるのを防ぐために、エンコードされたテキストに改行を挿入する。しかしオプション引数no-line-breakが非nilなら、これらの改行は追加されず、出力は長い単一の行となる。

Function: base64-encode-string string &optional no-line-break

この関数は、文字列stringをBase64コードに変換する。これはエンコードされたテキストを含む文字列をリターンする。base64-encode-regionと同様、文字列内の文字がマルチバイトならエラーをシグナルする。

通常この関数は行が長くなりすぎるのを防ぐために、エンコードされたテキストに改行を挿入する。しかしオプション引数no-line-breakが非nilなら、これらの改行は追加されず、結果となる文字列は長い単一の行となる。

Command: base64-decode-region beg end

この関数は、begからendのリージョンのBase64コードを、対応するデコードされたテキストに変換する。これはデコードされたテキストの長さをリターンする。

デコード関数は、エンコード済みテキスト内の改行文字を無視する。

Function: base64-decode-string string

この関数は、モジュールstringを、Base64コードから、対応するデコード済みテキストに変換する。これは、デコード済みテキストを含むユニバイトをリターンする。

デコード関数は、エンコード済みテキスト内の改行文字を無視する。

32.26 チェックサムとハッシュ

Emacs has built-in support for computing cryptographic hashes. A cryptographic hash, or checksum, is a digital fingerprint of a piece of data (e.g., a block of text) which can be used to check that you have an unaltered copy of that data.

Emacs supports several common cryptographic hash algorithms: MD5, SHA-1, SHA-2, SHA-224, SHA-256, SHA-384 and SHA-512. MD5 is the oldest of these algorithms, and is commonly used in message digests to check the integrity of messages transmitted over a network. MD5 is not collision resistant (i.e., it is possible to deliberately design different pieces of data which have the same MD5 hash), so you should not used it for anything security-related. A similar theoretical weakness also exists in SHA-1. Therefore, for security-related applications you should use the other hash types, such as SHA-2.

Function: secure-hash-algorithms: This function returns a list of symbols representing algorithms that secure-hash can use.

Function: secure-hash algorithm object &optional start end binary

この関数は、objectにたいするハッシュをリターンする。引数algorithmはどのハッシュを計算するかを示すシンボルでmd5、sha1、sha224、sha256、sha384、sha512のいずれかである。引数objectは、バッファーまたは文字列であること。

オプション引数startとendは、メッセージダイジェストを計算する、object部分を指定する文字位置である。これらがnilまたは省略された場合は、object全体にたいするハッシュを計算する。

引数binaryが省略またはnilなら、通常のLisp文字列として、そのハッシュのテキスト形式(text form)をリターンする。binaryが非nilなら、ユニバイト文字列に格納されたバイトシーケンスとして、そのハッシュのバイナリー形式(binary form)をリターンする。

この関数は、objectのテキストの内部表現(テキストの表現方法を参照)からハッシュを直接計算しない。かわりにコーディングシステム(コーディングシステムを参照)を使用してテキストをエンコードして、そのエンコード済みテキストからハッシュを計算する。objectがバッファーなら、使用されているコーディングが、そのテキストをファイルに書き込むためのデフォルトとして選択される。objectが文字列なら、ユーザーの好むコーディングシステムが使用される(Recognize Coding in GNU Emacs Manualを参照)。

Function: md5 object &optional start end coding-system noerror

この関数はMD5ハッシュをリターンする。これはほとんどの目的において、algorithm引数にmd5を指定してsecure-hashを呼び出すのと等価であり、半ば時代遅れである。引数のobject、start、endはsecure-hashのときと同じ意味をもつ。

coding-systemが非nilなら、それはテキストをエンコードするために使用する、コーディングシステムを指定する。if omitted or , the default coding system is used, like in secure-hashと同様にデフォルトコーディングシステムが使用される。

md5は通常、指定もしくは選択されたコーディングシステムを使用してテキストをエンコードできなければ、エラーをシグナルする。しかしnoerrorが非nilなら、かわりに黙ってraw-textコーディングシステムを使用する。

Function: buffer-hash &optional buffer-or-name: Return a hash of buffer-or-name. If nil, this defaults to the current buffer. As opposed to secure-hash, this function computes the hash based on the internal representation of the buffer, disregarding any coding systems. It’s therefore only useful when comparing two buffers running in the same Emacs, and is not guaranteed to return the same hash between different Emacs versions. It should be somewhat more efficient on larger buffers than secure-hash is, and should not allocate more memory.

32.27 GnuTLS Cryptography

If compiled with GnuTLS, Emacs offers built-in cryptographic support. Following the GnuTLS API terminology, the available tools are digests, MACs, symmetric ciphers, and AEAD ciphers.

The terms used herein, such as IV (Initialization Vector), require some familiarity with cryptography and will not be defined in detail. Please consult https://www.gnutls.org/ for specific documentation which may help you understand the terminology and structure of the GnuTLS library.

32.27.1 Format of GnuTLS Cryptography Inputs

The inputs to GnuTLS cryptographic functions can be specified in several ways, both as primitive Emacs Lisp types or as lists.

The list form is currently similar to how md5 and secure-hash operate.

buffer

Simply passing a buffer as input means the whole buffer should be used.

string

A string as input will be used directly. It may be modified by the function (unlike most other Emacs Lisp functions) to reduce the chance of exposing sensitive data after the function does its work.

(buffer-or-string start end coding-system noerror)

This specifies a buffer or a string as described above, but an optional range can be specified with start and end.

In addition an optional coding-system can be specified if needed.

The last optional item, noerror, overrides the normal error when the text can’t be encoded using the specified or chosen coding system. When noerror is non-nil, this function silently uses raw-text coding instead.

(iv-auto length)

This will generate an IV (Initialization Vector) of the specified length using the GnuTLS GNUTLS_RND_NONCE generator and pass it to the function. This ensures that the IV is unpredictable and unlikely to be reused in the same session. The actual value of the IV is returned by the function as described below.

32.27.2 GnuTLS Cryptographic Functions

Function: gnutls-digests

This function returns the alist of the GnuTLS digest algorithms.

Each entry has a key which represents the algorithm, followed by a plist with internal details about the algorithm. The plist will have :type gnutls-digest-algorithm and also will have the key :digest-algorithm-length 64 to indicate the size, in bytes, of the resulting digest.

There is a name parallel between GnuTLS MAC and digest algorithms but they are separate things internally and should not be mixed.

Function: gnutls-hash-digest digest-method input

The digest-method can be the whole plist from gnutls-digests, or just the symbol key, or a string with the name of that symbol.

The input can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs).

This function returns nil on error, and signals a Lisp error if the digest-method or input are invalid. On success, it returns a list of a binary string (the output) and the IV used.

Function: gnutls-macs

This function returns the alist of the GnuTLS MAC algorithms.

Each entry has a key which represents the algorithm, followed by a plist with internal details about the algorithm. The plist will have :type gnutls-mac-algorithm and also will have the keys :mac-algorithm-length :mac-algorithm-keysize :mac-algorithm-noncesize to indicate the size, in bytes, of the resulting hash, the key, and the nonce respectively.

The nonce is currently unused and only some MACs support it.

There is a name parallel between GnuTLS MAC and digest algorithms but they are separate things internally and should not be mixed.

Function: gnutls-hash-mac hash-method key input

The hash-method can be the whole plist from gnutls-macs, or just the symbol key, or a string with the name of that symbol.

The key can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs). The key will be wiped after use if it’s a string.

The input can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs).

This function returns nil on error, and signals a Lisp error if the hash-method or key or input are invalid.

On success, it returns a list of a binary string (the output) and the IV used.

Function: gnutls-ciphers

This function returns the alist of the GnuTLS ciphers.

Each entry has a key which represents the cipher, followed by a plist with internal details about the algorithm. The plist will have :type gnutls-symmetric-cipher and also will have the keys :cipher-aead-capable set to nil or t to indicate AEAD capability; and :cipher-tagsize :cipher-blocksize :cipher-keysize :cipher-ivsize to indicate the size, in bytes, of the tag, block size of the resulting data, the key, and the IV respectively.

Function: gnutls-symmetric-encrypt cipher key iv input &optional aead_auth

The cipher can be the whole plist from gnutls-ciphers, or just the symbol key, or a string with the name of that symbol.

The key can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs). The key will be wiped after use if it’s a string.

The iv and input and the optional aead_auth can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs).

aead_auth is only checked with AEAD ciphers, that is, ciphers whose plist has :cipher-aead-capable t. Otherwise it’s ignored.

This function returns nil on error, and signals a Lisp error if the cipher or key, iv, or input are invalid, or if aead_auth was specified with an AEAD cipher and was invalid.

On success, it returns a list of a binary string (the output) and the IV used.

Function: gnutls-symmetric-decrypt cipher key iv input &optional aead_auth

The cipher can be the whole plist from gnutls-ciphers, or just the symbol key, or a string with the name of that symbol.

The key can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs). The key will be wiped after use if it’s a string.

The iv and input and the optional aead_auth can be specified as a buffer or string or in other ways (see section Format of GnuTLS Cryptography Inputs).

aead_auth is only checked with AEAD ciphers, that is, ciphers whose plist has :cipher-aead-capable t. Otherwise it’s ignored.

This function returns nil on decryption error, and signals a Lisp error if the cipher or key, iv, or input are invalid, or if aead_auth was specified with an AEAD cipher and was invalid.

On success, it returns a list of a binary string (the output) and the IV used.

32.28 HTMLとXMLの解析

Emacsがlibxml2サポートつきでコンパイルされたときは、HTMLやXMLのテキストをLispオブジェクトツリーにパースするために、以下の関数が利用可能です。

Function: libxml-parse-html-region start end &optional base-url discard-comments

This function parses the text between start and end as HTML, and returns a list representing the HTML parse tree. It attempts to handle real-world HTML by robustly coping with syntax mistakes.

オプション引数base-urlが非nilなら、リンク内に出現する相対URLにたいする、ベースURLを指定する文字列であること。

If the optional argument discard-comments is non-nil, then the parse tree is created without any comments.

パースツリー内では、各HTMLノードは1つ目の要素がノード名を表すシンボル2つ目の要素がノード属性のalist、残りの要素はサブノードであるようなリストにより表される。

以下の例でこれを示す。以下の(不正な)HTMLドキュメントを与えると:

<html><head></head><body width=101><div class=thing>Foo<div>Yes

A call to libxml-parse-html-region returns this DOM (document object model):

(html nil
 (head nil)
 (body ((width . "101"))
  (div ((class . "thing"))
   "Foo"
   (div nil
    "Yes"))))

Function: shr-insert-document dom: この関数は、dom内のパース済みHTMLを、カレントバッファー内に描画する。引数domは、libxml-parse-html-regionで整数されるようなｌリストであること。この関数はたとえば、EWW in The Emacs Web Wowser Manualにより使用される。

Function: libxml-parse-xml-region start end &optional base-url discard-comments: この関数はlibxml-parse-html-regionと同様だが、HTMLではなく(構文についてより厳格な)XMLとしてテキストをパースする点が異なる。

32.28.1 Document Object Model

The DOM returned by libxml-parse-html-region (and the other XML parsing functions) is a tree structure where each node has a node name (called a tag), and optional key/value attribute list, and then a list of child nodes. The child nodes are either strings or DOM objects.

(body ((width . "101"))
 (div ((class . "thing"))
  "Foo"
  (div nil
   "Yes")))

Function: dom-node tag &optional attributes &rest children: This function creates a DOM node of type tag. If given, attributes should be a key/value pair list. If given, children should be DOM nodes.

The following functions can be used to work with this structure. Each function takes a DOM node, or a list of nodes. In the latter case, only the first node in the list is used.

Simple accessors:

dom-tag node

Return the tag (also called “node name”) of the node.

dom-attr node attribute

Return the value of attribute in the node. A common usage would be:

(dom-attr img 'href)
=> "https://fsf.org/logo.png"

dom-children node

Return all the children of the node.

dom-non-text-children node

Return all the non-string children of the node.

dom-attributes node

Return the key/value pair list of attributes of the node.

dom-text node

Return all the textual elements of the node as a concatenated string.

dom-texts node

Return all the textual elements of the node, as well as the textual elements of all the children of the node, recursively, as a concatenated string. This function also takes an optional separator to be inserted between the textual elements.

dom-parent dom node

Return the parent of node in dom.

dom-remove dom node

Remove node from dom.

The following are functions for altering the DOM.

dom-set-attribute node attribute value: Set the attribute of the node to value.
dom-append-child node child: Append child as the last child of node.
dom-add-child-before node child before: Add child to node’s child list before the before node. If before is nil, make child the first child.
dom-set-attributes node attributes: Replace all the attributes of the node with a new key/value list.

The following are functions for searching for elements in the DOM. They all return lists of matching nodes.

dom-by-tag dom tag

Return all nodes in dom that are of type tag. A typical use would be:

(dom-by-tag dom 'td)
=> '((td ...) (td ...) (td ...))

dom-by-class dom match

Return all nodes in dom that have class names that match match, which is a regular expression.

dom-by-style dom style

Return all nodes in dom that have styles that match match, which is a regular expression.

dom-by-id dom style

Return all nodes in dom that have IDs that match match, which is a regular expression.

dom-strings dom

Return all strings in dom.

Utility functions:

dom-pp dom &optional remove-empty: Pretty-print dom at point. If remove-empty, don’t print textual nodes that just contain white-space.

32.29 グループのアトミックな変更

データベース用語でアトミック(atomic: 原子的、不可分な)変更とは、全体として成功もしくは失敗することはできるが、部分的にはできない、個別の変更のことです。Lispプログラムは単一もしくは複数のバッファーにたいする一連の変更をアトミック変更グループ(atomic change group)にすることができます。これはその一連の変更全体が、それらのバッファーに適用されるか、またはエラーの場合は何も適用されないかの、いずれかであることを意味します。

すでにカレントであるような単一のバッファーにたいしてこれを行うには、以下のように変更を行うこーの周りに、単にatomic-change-groupの呼び出しを記述します:

(atomic-change-group
  (insert foo)
  (delete-region x y))

atomic-change-groupのbody内部でエラー(またはその他の非ローカルexit)が発生した場合は、そのbody実行の間にそのバッファーでのすべての変更が行われなかったことになります。この類の変更グループは、他のバッファーには影響を与えず、それらのバッファーにたいする変更はそのまま残されます。

さまざまなバッファー内で行った変更から1つのアトミックグループを構成する等、より複雑な何かを必要とする場合は、atomic-change-groupが使用する、より低レベルな関数を直接呼び出さなければなりません。

Function: prepare-change-group &optional buffer: This function sets up a change group for buffer buffer, which defaults to the current buffer. It returns a handle that represents the change group. You must use this handle to activate the change group and subsequently to finish it.

変更グループを使用するためには、それをactivate(アクティブ化)しなければなりません。これはbufferのテキストを変更する前に行わなければなりません。

Function: activate-change-group handle: これは、handleが指定する変更グループをactiveにする。

変更グループをactivateした後は、そのバッファー内で行ったすべての変更は、その変更グループの一部となります。そのバッファー内で目論んでいたすべての変更を行ったら、その変更グループをfinish(完了)しなければなりません。すべての変更を受け入れる(確定する)か、すべてをキャンセルするという2つの方法により、これを行うことができます。

Function: accept-change-group handle: この関数はhandleにより指定される変更グループ内のすべての変更にたいして、finalizeすることにより変更を受け入れる。

Function: cancel-change-group handle: この関数はhandleにより指定される変更グループ内のすべての変更をキャンセルしてundoする。

グループが常に確実にfinishされるようにするために、コードではunwind-protectを使用するべきです。activate-change-groupの呼び出しは、実行直後にユーザーがC-gをタイプする場合に備え、unwind-protect内部にあるべきです(これがprepare-change-groupとactivate-change-groupが別関数となっている1つの理由である。なぜなら通常はunwind-protect開始前にprepare-change-groupを呼び出すであろうから)。グループを一度finishしたら、そのhandleを再度使用してはなりません。特に、同じ変更グループを2回finishしないでください。

複数バッファー変更グループ(multibuffer change group)を作成するためには、カバーしたいバッファーそれぞれでprepare-change-groupを一度呼び出してから、以下のようにリターン値を結合するために、nconcを使用してください:

(nconc (prepare-change-group buffer-1)
       (prepare-change-group buffer-2))

その後は1回のactivate-change-group呼び出しで複数変更グループをアクティブにして、1回のaccept-change-groupまたはcancel-change-group呼び出しで、それをfinishしてください。

同一バッファーにたいするネストされた複数の変更グループ使用は、あなたが期待するであろう通り機能します。同一バッファーにたいするネストされていない変更グループ使用により、Emacsが混乱した状態になるため、これが発生しないようにしてください。与えられた何らかのバッファーにたいして最初に開始した変更グループは、最後にfinishする変更グループです。

32.30 フックの変更

These hook variables let you arrange to take notice of changes in buffers (or in a particular buffer, if you make them buffer-local). See also 特殊な意味をもつプロパティ, for how to detect changes to specific parts of the text.

これらのフック内で使用する関数は、もしそれらが正規表現を使用して何かを行う場合は、マッチしたデータの保存とリストアを行うべきです。さもないと、それらが呼び出す編集処理に、奇妙な方法で干渉するでしょう。

Variable: before-change-functions: This variable holds a list of functions to call when Emacs is about to modify a buffer. Each function gets two arguments, the beginning and end of the region that is about to change, represented as integers. The buffer that is about to change is always the current buffer when the function is called.

Variable: after-change-functions

This variable holds a list of functions to call after Emacs modifies a buffer. Each function receives three arguments: the beginning and end of the region just changed, and the length of the text that existed before the change. All three arguments are integers. The buffer that has been changed is always the current buffer when the function is called.

古いテキストの長さは、変更される前のテキストでの、そのテキストの前後のバッファー位置の差である。変更されたテキストでは、その長さは単に最初の2つの引数の差である。

Output of messages into the *Messages* buffer does not call these functions, and neither do certain internal buffer changes, such as changes in buffers created by Emacs internally for certain jobs, that should not be visible to Lisp programs.

The vast majority of buffer changing primitives will call before-change-functions and after-change-functions in balanced pairs, once for each change, where the arguments to these hooks exactly delimit the change being made. Yet, hook functions should not rely on this always being the case, because some complex primitives call before-change-functions once before making changes, and then call after-change-functions zero or more times, depending on how many individual changes the primitive is making. When that happens, the arguments to before-change-functions will enclose a region in which the individual changes are made, but won’t necessarily be the minimal such region, and the arguments to each successive call of after-change-functions will then delimit the part of text being changed exactly. In general, we advise to use either before- or the after-change hooks, but not both.

Macro: combine-after-change-calls body…

このマクロは普通にbodyを実行するが、もしそれが安全なように見えるなら、一連の複数の変更にたいして正に一度、after-change関数を呼び出すようにアレンジする。

そのバッファーの同じ領域内でプログラムが複数のテキスト変更を行う場合は、その部分のプログラムの周囲でマクロcombine-after-change-callsを使用することにより、after-changeフック使用中の実行がかなり高速になり得る。after-changeフックが最終的に呼び出される際、その引数はcombine-after-change-callsのbody内で行われたすべての変更にたいして含むバッファーの範囲を指定する。

警告: フォームcombine-after-change-callsのbody内で、after-change-functionsの値を変更してはならない。

警告: 組み合わされた変更がバッファーの広い範囲にばらばらに発生する場合でも、これは依然として機能するものの、お勧めはできない。なぜならこれは、ある変更フック関数を、非効率的な挙動へと導くかもしれないからである。

Variable: first-change-hook: この変数は、以前は未変更の状態だったバッファーが変更された際は常に実行されるノーマルフックである。

Variable: inhibit-modification-hooks

この変数が非nilなら、すべての変更フックは無効になる。それらは何も実行されない。これはこのセクションで説明したすべてのフック変数、同様に特定のスペシャルテキストプロパティ(特殊な意味をもつプロパティを参照)とオーバーレイプロパティ(オーバーレイのプロパティを参照)にアタッチされたフックに影響を与える。

これらの同じフック変数実行の間、バッファー変更によるデフォルトの変更フックが他の変更フック実行中に実行されないように、この変数は非nilにバインドされるそれ自体が変更フックから実行される特定のコード断片内で変更フックを実行したければ、ローカルにinhibit-modification-hooksをnilに再バインドすること。

33 非ASCII文字

このチャプターは文字に関する特別な問題と、それらが文字列およびバッファーに格納される方法についてカバーします。

33.1 テキストの表現方法		Emacsがテキストを表す方法。
33.2 マルチバイト文字の無効化		マルチバイト使用を制御する。
33.3 テキスト表現の変換		ユニバイトとマルチバイトの相互変換。
33.4 表現の選択		バイトシーケンスをユニバイトやマルチバイトとして扱う。
33.5 文字コード		ユニバイトやマルチバイトが個々の文字のコードと関わる方法。
33.6 文字のプロパティ		文字の挙動と処理を定義する文字属性。
33.7 文字セット		利用可能な文字コード空間はさまざまな文字セットに分割される。
33.8 文字セットのスキャン		バッファーで使用されている文字セットは?
33.9 文字の変換		変換に使用される変換テーブル。
33.10 コーディングシステム		コーディングシステムはファイル保存のための変換である。
33.11 入力メソッド		入力メソッドによりユーザーは特別なキーボードなしで非ASCII文字を入力できる。
33.12 locale		POSIX localeとの対話。

33.1 テキストの表現方法

Emacsのバッファーおよび文字列は、既知のスクリプトで記述されたほとんどすべてのテキストをユーザーがタイプしたり表示できるよう、多種多様な言語の広大な文字レパートリーをサポートします。

多種多様な文字およびスクリプトをサポートするために、EmacsはUnicode標準(Unicode Standard)に厳密にしたがいます。Unicode標準は、すべての文字にたいしてそれぞれ、コードポイント(codepoint)と呼ばれる一意な番号を割り当てています。コードポイントの範囲はUnicode、またはUnicodeコード空間(codespace)により定義され、範囲は0..#x10FFFF(16進表記、範囲両端を含む)です。Emacsはこれを、範囲#x110000..#x3FFFFFのコードポイント範囲に拡張します。この範囲はUnicodeとして統一されていない文字や、文字として解釈できない8ビットrawバイト(raw 8-bit bytes)を表すために使用します。したがって、Emacs内の文字コードポイントは、22ビットの整数になります。

メモリー節約のため、Emacsはバッファーおよび文字列内のテキスト文字にたいするコードポイントである、22ビットの整数を固定長で保持しません。かわりに、Emacsは文字の内部表現として可変長を使用します。これは、そのコードポイントの値に応じて、各文字を5ビットから8ビットのバイトシーケンスとして格納するものです¹⁵。たとえばすべてのASCII文字は1バイト、Latin-1文字は2バイトといった具合です。わたしたちはこれを、テキストのマルチバイト(multibyte)表現と呼んでいます。

Emacs外部では、ISO-8859-1、GB-2312、Big-5等のような多種の異なるエンコーディングで文字を表すことができます。Emacsはバッファーまたは文字列へのテキスト読み込み時、およびディスク状のファイルへのテキスト書き込みや他プロセスへの引き渡し時に、これらの外部エンコーディングと、その内部表現の間で適切な変換を行います。

Emacsがエンコード済みテキストや非テキストデータを、バッファーや文字列に保持、あるいは操作する必要がある場合も時折あります。たとえばEmacsがファイルをvisitする際、まずそのファイルのテキストをそのままバッファーに読み込み、その後にのみそれを内部表現に変換します。この変換前にバッファーに保持されてくださいのは、エンコード済みのテキストです。

Emacsに関する限り、エンコードされたテキストは実際のテキストではなく、8ビットrawバイトです。エンコード済みテキストを保持するバッファーおよび文字列は、Emacsがそれらを個々のバイトシーケンスとしてアツカウことから、ユニバイト(unibyte)のバッファーまたは文字列と呼んでいます。Emacsは通常、ユニバイトのバッファーおよび文字列を、\237のような8進コードで表示します。エンコード済みテキストやバイナリー非テキストデータを処理する場合を除き、ユニバイトバッファーとユニバイト文字列は決して使用しないよう推奨します。

バッファーにおいては、変数enable-multibyte-charactersのバッファーローカルな値が、使用する表現を指定します。文字列での表現は、その文字列構築時に判断して、それを文字列内に記録します。

Variable: enable-multibyte-characters

この変数は、カレントバッファーのテキスト表現を指定する。非nilならバッファーはマルチバイトテキストを含み、それ以外ならエンコード済みユニバイトテキスト、またはバイナリー非テキストデータが含れる。

この変数は直接セットできない。バッファーの表現を変更するには、かわりに関数set-buffer-multibyteを使用すること。

Function: position-bytes position: バッファー位置は文字単位で測られる。この関数は、カレントバッファー内のバッファー位置を、それに対応するバイト位置でリターンする。これはバッファー先頭を1として、バイト単位で増加方向に数えられる。positionが範囲外なら、値はnilになる。

Function: byte-to-position byte-position: カレントバッファー内で、与えられたbyte-positionに対応するバッファー位置を、文字単位でリターンする。byte-positionが範囲外なら、値はnilになる。マルチバイトバッファーでは、byte-positionの任意の値が文字境界上になく、1文字として表現されたマルチバイトシーケンス内にあるかもしれない。この場合、関数はその文字のマルチバイトシーケンスがbyte-positionを含むようなバッファー位置をリターンする。言い換えると、この値は同じ文字に属するすべてのバイト位置にたいして変化しない。

The following two functions are useful when a Lisp program needs to map buffer positions to byte offsets in a file visited by the buffer.

Function: bufferpos-to-filepos position &optional quality coding-system

This function is similar to position-bytes, but instead of byte position in the current buffer it returns the offset from the beginning of the current buffer’s file of the byte that corresponds to the given character position in the buffer. The conversion requires to know how the text is encoded in the buffer’s file; this is what the coding-system argument is for, defaulting to the value of buffer-file-coding-system. The optional argument quality specifies how accurate the result should be; it should be one of the following:

exact: The result must be accurate. The function may need to encode and decode a large part of the buffer, which is expensive and can be slow.
approximate: The value can be an approximation. The function may avoid expensive processing and return an inexact result.
nil: If the exact result needs expensive processing, the function will return nil rather than an approximation. This is the default if the argument is omitted.

Function: filepos-to-bufferpos byte &optional quality coding-system: This function returns the buffer position corresponding to a file position specified by byte, a zero-base byte offset from the file’s beginning. The function performs the conversion opposite to what bufferpos-to-filepos does. Optional arguments quality and coding-system have the same meaning and values as for bufferpos-to-filepos.

Function: multibyte-string-p string: stringがマルチバイト文字列ならt、それ以外はnilをリターンする。この関数は、stringが文字列以外の場合にも、nilをリターンする。

Function: string-bytes string: この関数は、string内のバイトの数をリターンする。stringがマルチバイト文字列なら、これは(length string)より大きいかもしれない。

Function: unibyte-string &rest bytes: この関数は引数bytesをすべて結合して、その結果をユニバイト文字列で作成する。

33.2 マルチバイト文字の無効化

デフォルトでは、Emacsはマルチバイトモードで開始します。Emacsは、マルチバイトシーケンスを使用して非ASCII文字を表現する内部エンコーディングを使用することにより、バッファーおよび文字列のコンテンツを格納します。マルチバイトモードではサポートされるすべての言語とスクリプトを使用できます。

非常に特別な状況下においては、特定のバッファーでマルチバイト文字のサポートを無効にしたいときがあるかもしれません。あるバッファーにおいてマルチバイト文字が無効になっているときは、それをユニバイトモード(unibyte mode)と呼びます。ユニバイトモードでは、バッファー内の各文字は0から255(8進の0377)の範囲の文字コードをもちます。0から127(8進の0177)はASCII文字、128から255(8進の0377)は非ASCII文字を表します。

特定のファイルをユニバイト表現で編集するためには、find-file-literallyを使用してファイルをvisitします。ファイルをvisitする関数を参照してください。マルチバイトバッファーをファイルに保存してバッファーをkillした後に、再びそのファイルをfind-file-literallyでvisitすることにより、マルチバイトバッファーをユニバイトに変換できます。かわりにC-x RET c(universal-coding-system-argument)を使用して、ファイルをvisitまたは保存するコーディングシステムとして‘raw-text’を指定することもできます。Specifying a Coding System for File Text in GNU Emacs Manualを参照してください。find-file-literallyとは異なり、‘raw-text’としてファイルをvisitしてもフォーマット変換、解凍、自動的なモード選択は無効になりません。

バッファーローカル変数enable-multibyte-charactersは、マルチバイトバッファーなら非nil、ユニバイトバッファーならnilになります。マルチバイトバッファーかどうかは、モードラインにも示されます。グラフィカルなディスプレイでのマルチバイトバッファーは、文字セット話示すモードライン部分ぬ、そのバッファーがマルチバイトであること(とそれ以外の事項)を告げるツールチップがあります。ユニバイトバッファーでは、文字セットのインジケーターはありません。したがって(グラフィカルなディスプレイ使用時の)ユニバイトバッファーでは、入力メソッドを使用していなければ、visitしているファイルの行末変換(コロン、バックスラッシュ等)の標識の前には通常何も標識はありません。

特定のバッファーでマルチバイトサポートをオフに切り替えるには、そのバッファー内でコマンドtoggle-enable-multibyte-charactersを呼び出してください。

33.3 テキスト表現の変換

Emacsはユニバイトテキストをマルチバイトに変換できます。マルチバイトテキストに含まれるのがASCIIと8ビットrawバイトだけという条件つきで、マルチバイトテキストからユニバイトへの変換もできます。一般的にこれらの変換はバッファーへのテキスト挿入時、または複数の文字列を1つの文字列に合わせてテキストにputするときに発生します。文字列のコンテンツを、いずれかの表現に明示的に変換することもできます。

Emacsは、そのテキストの構成にもとづいて、文字列の表現を選択します。一般的なルールでは、ユニバイトテキストが他のマルチバイトテキストと組み合わされている場合は、マルチバイト表現のほうがより一般的であり、ユニバイトテキストのすべての文字を保有できるので、ユニバイトテキストをマルチバイトテキストに変換します。

バッファーへのテキスト挿入時、Emacsはそのバッファーのenable-multibyte-charactersで指定されるように、テキストをそのバッファーの表現に変換します。特にユニバイトバッファーへマルチバイトテキストを挿入する際は、たとえ一般的にはマルチバイトテキスト内のすべての文字を保持することはできなくても、Emacsはテキストをユニバイトに変換します。バッファーコンテンツをマルチバイトに変換するという自然な代替方法は、そのバッファーの表現が自動的にオーバーライドできないユーザーによる選択にもとづく表現であるため、受け入れられません。

ユニバイトテキストからマルチバイトテキストへの変換では、ASCII文字は未変更のまま残され、128から255のコードをもつバイトが8ビットrawバイトのマルチバイト表現に変換されます。

マルチバイトテキストからユニバイトテキストへの変換では、すべてのASCIIと8ビット文字が、それらの1バイト形式に変換されますが、各文字のコードポイントの描い8ビット以外は破棄されるため、非ASCII文字の情報は失われます。ユニバイトテキストからマルチバイトテキストに変換して、それをユニバイトに戻せば、元のユニバイトテキストが再生成されます。

以下の2つの関数は、引数string、またはテキストプロパティをもたない新たに作成された文字列のいずれかをリターンします。

Function: string-to-multibyte string: この関数は、stringと同じ文字シーケンスを含むマルチバイト文字列をリターンする。stringがマルチバイト文字列なら、それが未変更のままリターンされる。この関数は、stringがASCII文字と8ビットrawバイトだけを含むと仮定する。後者は#x3FFF80から#x3FFFFF(両端を含む)に対応する、8ビットrawバイトのマルチバイト表現に変換される(codepointsを参照)。

Function: string-to-unibyte string: この関数は、stringと同じ文字シーケンスを含む、ユニバイト文字列をリターンする。stringに非ASCII文字が含まれる場合は、エラーをシグナルする。stringがユニバイト文字列なら、それが未変更のままリターンされる。ASCII文字と8ビット文字だけを含むstring引数にたいしてのみ、この関数を使用すること。

Function: byte-to-string byte: この関数は、文字データbyteの単一バイトを含むユニバイト文字列をリターンする。byteが0から255までの整数でなければ、エラーをシグナルする。

Function: multibyte-char-to-unibyte char: これはマルチバイト文字charをユニバイト文字に変換して、その文字をリターンする。charがASCIIと8ビットのいずれでもなければ、この関数は-1をリターンする。

Function: unibyte-char-to-multibyte char: これはcharがASCIIか8ビットrawバイトのいずれかであると仮定して、ユニバイト文字ASCIIをマルチバイト文字に変換する。

33.4 表現の選択

既存のバッファーまたは文字列がユニバイトの際にそれらをマルチバイトとして調べたり、その逆を行うことが有用なときがあります。

Function: set-buffer-multibyte multibyte

カレントバッファーの表現タイプをセットする。multibyteが非nilならバッファーはマルチバイト、nilならユニバイトになる。

この関数は、バイトシーケンスとして認識時には、バッファーを未変更のままとする。結果として、文字として認識時にはコンテンツを変更できる。たとえば、マルチバイト表現では1文字として扱われる3バイトのシーケンスは、ユニバイト表現では3文字として数えられるだろう。例外はrawバイトを表す8ビット文字である。これらはユニバイトバッファーでは1バイトで表現されるが、バッファーをマルチバイトにセットした際は2バイトのシーケンスに変換され、その逆の変換も行われる。

この関数は、どの表現が使用されているかを記録するために、enable-multibyte-charactersをセットする。これは以前の同じテキストをカバーするよう、バッファー内のさまざまなデータ(オーバーレイ、テキストプロパティ、マーカーを含む)を調整する。

ナローイングはマルチバイト文字シーケンス中間で発生するかもしれないので、この関数はバッファーがナローイングされている場合はエラーをシグナルする。

そのバッファーがインダイレクトバッファー(indirect buffer: 間接バッファー)の場合も、エラーをシグナルする。インダイレクトバッファーは、常にベースバッファー(base buffer: 基底バッファー)の表現を継承する。

Function: string-as-unibyte string: stringがすでにユニバイト文字列なら、この関数はstring自身をリターンする。それ以外はstringと同じバイトだが、それぞれの文字を個別の文字としてとして扱い、新たな文字列をリターンする(値はstringより多くの文字をもつかもしれない)。例外として、rawバイトを表す8ビット文字はそれぞれ、単一のバイトに変換される。新たに作成された文字列に、テキストプロパティは含まれない。

Function: string-as-multibyte string: stringがすでにマルチバイト文字列なら、この関数はstring自身をリターンする。それ以外はstringと同じバイトだが、それぞれのマルチバイトシーケンスを1つの文字としてとして扱い、新たな文字列をリターンする。これは、値がstringより少ない文字をもつかもしれないことを意味する。string内のバイトシーケンスが、単一文字のマルチバイト表現として無効なら、そのシーケンスないの各バイトは、8ビットrawバイトとして扱われる。新たに作成された文字列には、テキストプロパティは含まれない

33.5 文字コード

ユニバイトおよびマルチバイトのテキスト表現は、異なる文字コードを使用します。ユニバイト表現にたいして有効な文字コードの範囲は0から#xFF(255)で、これは1バイトに収まる値です。マルチバイト表現にたいして有効な文字コードの範囲は、0から#x3FFFFFです。このコード空間では値0から#x7F(127)がASCII文字用、値#x80(128)から#x3FFF7F(4194175)が非ASCII文字用になります。

Emacsの文字コードは、Unicode標準の上位集合(superset)です。値0から#x10FFFF(1114111)は、同じコードポイントのUnicode文字に対応します。値#x110000(1114112)から#x3FFF7F(4194175)は、Unicodeに統一されていない文字を、値#x3FFF80 (4194176)から#x3FFFFF(4194303)は8ビットrawバイトを表します。

Function: characterp charcode

これはcharcodeが有効な文字ならt、それ以外はnilをリターンする。

(characterp 65)
     ⇒ t

(characterp 4194303)
     ⇒ t

(characterp 4194304)
     ⇒ nil

Function: max-char

この関数は、有効な文字コードポイントがもち得る最大の値をリターンする。

(characterp (max-char))
     ⇒ t

(characterp (1+ (max-char)))
     ⇒ nil

Function: char-from-name string &optional ignore-case

This function returns the character whose Unicode name is string. If ignore-case is non-nil, case is ignored in string. This function returns nil if string does not name a character.

;; U+03A3
(= (char-from-name "GREEK CAPITAL LETTER SIGMA") #x03A3)
     ⇒ t

Function: get-byte &optional pos string

この関数は、カレントバッファー内の文字位置posにあるバイトをリターンする。カレントバッファーがユニバイトなら、その位置のバイトをそのままリターンする。バッファーがマルチバイトの場合は、8ビットrawバイトは8ビットコードに変換される一方、ASCII文字のバ値は文字コードポイントと同じになる。この関数は、posにある文字が非ASCIIなら、エラーをシグナルする。

オプション引数stringは、カレントバッファーのかわりに、文字列からバイト値を得ることを意味する。

33.6 文字のプロパティ

文字プロパティ(character propertyとは、その文字の振る舞いと、テキストが処理および表示される間どのように処理されるべきかを指定する、名前つきの文字属性です。したがって文字プロパティは、その文字の意味を指定するための重要な一部です。

全体として、Emacsは自身の文字プロパティ実装においてはUnicode標準にしたがいます。特にEmacsはUnicode Character Property Modelをサポートしており、Emacs文字プロパティデータベースはUnicode文字データベース(UCD: Unicode Character Database)から派生したものです。Unicode文字プロパティとその意味についての詳細な説明は、Character Properties chapter of the Unicode Standardを参照してください。このセクションでは、あなたがすでにUnicode標準の該当する章に親しんでいて、その知識をEmacs Lispプログラムに適用したいものと仮定します。

Emacsでは、各プロパティは名前をもつシンボルであり、そのシンボルは利用可能な値セットをもち、値の型はプロパティに依存します。ある文字が特定のプロパティをもたなければ、その値はnilになります。一般的なルールとして、Emacsでの文字プロパティ名は、対応するUnicodeプロパティ名を小文字にして、文字‘_’をダッシュ文字‘-’で置き換えることにより生成されます。たとえばCanonical_Combining_Classはcanonical-combining-classとなります。しかし簡単に使用できるように、名前を短くすることもあります。

UCDによりいくつかのコードポイントは未割り当て(unassigned)のまま残されており、それらに対応する文字はありません。Unicode標準は、そのようなコードポイントのプロパティにたいしてデフォルト値を定義しています。それらについては、以下の各プロパティごとに注記しています。

以下は、Emacsが関知するすべての文字プロパティにたいする、値タイプの完全なリストです:

name: UnicodeプロパティNameに対応する。値はラテン大文字のAからZ、数字、スペース、ハイフン‘-’の文字から構成される文字列である。未割り当てのコードポイントにたいする値はnil。
general-category: UnicodeプロパティGeneral_Categoryに対応する。値は、その文字の分類をアルファベット2文字に略したものを名前としてもつようなシンボルである。未割り当てのコードポイントにたいする値はCn。
canonical-combining-class: UnicodeプロパティCanonical_Combining_Classに対応する。値は整数。未割り当てのコードポイントにたいする値は0。
bidi-class: UnicodeプロパティBidi_Classに対応する。値は、その文字のUnicode方向タイプ(directional type)が名前であるようなシンボル。Emacsは表示のために双方向テキストを並び替える際に、このプロパティを使用する(双方向テキストの表示を参照)。未割り当てのコードポイントにたいする値は、そのコードポイントが属するコードブロックに依存する。未割り当てのコードポイントのほとんどはL(強い左方向)だが、AL( Arabic letter: アラビア文字)やR(強い右方向)を受け取るコースポイントもいくつかある。
decomposition: Corresponds to the Unicode properties Decomposition_Type and Decomposition_Value. The value is a list, whose first element may be a symbol representing a compatibility formatting tag, such as small¹⁶; the other elements are characters that give the compatibility decomposition sequence of this character. For characters that don’t have decomposition sequences, and for unassigned codepoints, the value is a list with a single member, the character itself.
decimal-digit-value: Corresponds to the Unicode Numeric_Value property for characters whose Numeric_Type is ‘Decimal’. The value is an integer, or nil if the character has no decimal digit value. For unassigned codepoints, the value is nil, which means NaN, or “not a number”.
digit-value: Corresponds to the Unicode Numeric_Value property for characters whose Numeric_Type is ‘Digit’. The value is an integer. Examples of such characters include compatibility subscript and superscript digits, for which the value is the corresponding number. For characters that don’t have any numeric value, and for unassigned codepoints, the value is nil, which means NaN.
numeric-value: Corresponds to the Unicode Numeric_Value property for characters whose Numeric_Type is ‘Numeric’. The value of this property is a number. Examples of characters that have this property include fractions, subscripts, superscripts, Roman numerals, currency numerators, and encircled numbers. For example, the value of this property for the character U+2155 (VULGAR FRACTION ONE FIFTH) is 0.2. For characters that don’t have any numeric value, and for unassigned codepoints, the value is nil, which means NaN.
mirrored: UnicodeプロパティBidi_Mirroredに対応する。このプロパティの値は、YまたはNいずれかのシンボル。未割り当てのコードポイントにたいする値はN。
mirroring: UnicodeプロパティBidi_Mirroring_Glyphに対応する。このプロパティの値は、そのグリフ(glyph)がその文字のグリフの鏡像(mirror image)を表すような文字、定義済みの鏡像グリフがなければnilである。mirroredプロパティがNであるようなすべての文字のmirroringプロパティはnilである。しかしmirroredプロパティがYの文字でも、鏡像をもつ適切な文字がないという理由により、mirroringがnilの文字もある。Emacsは適切な際は、鏡像を表示するためにこのプロパティを使用する(双方向テキストの表示を参照)。未割り当てのコードポイントにたいする値はnil。
paired-bracket: Corresponds to the Unicode Bidi_Paired_Bracket property. The value of this property is the codepoint of a character’s paired bracket, or nil if the character is not a bracket character. This establishes a mapping between characters that are treated as bracket pairs by the Unicode Bidirectional Algorithm; Emacs uses this property when it decides how to reorder for display parentheses, braces, and other similar characters (see section 双方向テキストの表示).
bracket-type: Corresponds to the Unicode Bidi_Paired_Bracket_Type property. For characters whose paired-bracket property is non-nil, the value of this property is a symbol, either o (for opening bracket characters) or c (for closing bracket characters). For characters whose paired-bracket property is nil, the value is the symbol n (None). Like paired-bracket, this property is used for bidirectional display.
old-name: Corresponds to the Unicode Unicode_1_Name property. The value is a string. For unassigned codepoints, and characters that have no value for this property, the value is nil.
iso-10646-comment: Corresponds to the Unicode ISO_Comment property. The value is either a string or nil. For unassigned codepoints, the value is nil.
uppercase: UnicodeプロパティSimple_Uppercase_Mappingに対応する。このプロパティの値は、単一の文字。未割り当てのコードポイントの値はnilで、これはその文字自身を意味する。
lowercase: UnicodeプロパティSimple_Lowercase_Mappingに対応する。このプロパティの値は、単一の文字。未割り当てのコードポイントの値はnilで、これはその文字自身を意味する。
titlecase: UnicodeプロパティSimple_Titlecase_Mappingに対応する。タイトルケース(title case)とは、単語の最初の文字を大文字にする必要がある際に使用される、文字の特別な形式のこと。このプロパティの値は、単一の文字。未割り当てのコードポイントにたいする値はnilで、これはその文字自身を意味する。
special-uppercase: Corresponds to Unicode language- and context-independent special upper-casing rules. The value of this property is a string (which may be empty). For example mapping for U+00DF (LATIN SMALL LETTER SHARP S) is "SS". For characters with no special mapping, the value is nil which means uppercase property needs to be consulted instead.
special-lowercase: Corresponds to Unicode language- and context-independent special lower-casing rules. The value of this property is a string (which may be empty). For example mapping for U+0130 (LATIN CAPITAL LETTER I WITH DOT ABOVE) the value is "i\u0307" (i.e. 2-character string consisting of LATIN SMALL LETTER I followed by COMBINING DOT ABOVE). For characters with no special mapping, the value is nil which means lowercase property needs to be consulted instead.
special-titlecase: Corresponds to Unicode unconditional special title-casing rules. The value of this property is a string (which may be empty). For example mapping for U+FB01 (LATIN SMALL LIGATURE FI) the value is "Fi". For characters with no special mapping, the value is nil which means titlecase property needs to be consulted instead.

Function: get-char-code-property char propname

この関数は、charのプロパティpropnameの値をリターンする。

(get-char-code-property ?\s 'general-category)
     ⇒ Zs

(get-char-code-property ?1 'general-category)
     ⇒ Nd

;; U+2084
(get-char-code-property ?\N{SUBSCRIPT FOUR}
                        'digit-value)
     ⇒ 4

;; U+2155
(get-char-code-property ?\N{VULGAR FRACTION ONE FIFTH}
                        'numeric-value)
     ⇒ 0.2

;; U+2163
(get-char-code-property ?\N{ROMAN NUMERAL FOUR}
                        'numeric-value)
     ⇒ 4

(get-char-code-property ?\( 'paired-bracket)
     ⇒ 41  ;; closing parenthesis

(get-char-code-property ?\) 'bracket-type)
     ⇒ c

Function: char-code-property-description prop value

この関数はプロパティpropのvalueの説明文字列(description string)、valueが説明をもたなければnilをリターンする。

(char-code-property-description 'general-category 'Zs)
     ⇒ "Separator, Space"

(char-code-property-description 'general-category 'Nd)
     ⇒ "Number, Decimal Digit"

(char-code-property-description 'numeric-value '1/5)
     ⇒ nil

Function: put-char-code-property char propname value: この関数は、文字charのプロパティpropnameの値として、valueを格納する。

Variable: unicode-category-table: この変数の値は、それぞれの文字にたいして、そのUnicodeプロパティGeneral_Categoryをシンボルとして指定する、文字テーブルである(文字テーブルを参照)。

Variable: char-script-table: この変数の値は、それぞれの文字がシンボルを指定するような文字テーブルである。シンボルの名前は、Unicodeコードスペースからスクリプト固有ブロックへのUnicode標準分類にしたがった、その文字が属するスクリプトである。この文字テーブルは余分のスロットを１つもち、値はすべてのスクリプトシンボルのリストである。

Variable: char-width-table: この変数の値は、、それぞれの文字がスクリーン上で占めるであろう幅を列単位で指定する、文字テーブルである。

Variable: printable-chars: この変数の値は、それぞれの文字にたいして、それがプリント可能かどうかを指定する、文字テーブルである。すなわち、(aref printable-chars char)を評価した結果がtならプリント可で、nilなら不可である。

33.7 文字セット

Emacsの文字セット(character set、もしくはcharset)とは、それぞれの文字が数字のコードポイントに割り当てられれた、文字セットのことです(Unicode標準ではこれを符号化文字集合(coded character set)と呼ぶ)。Emacsの各文字セットは、シンボルであるような名前をもちます。1つの文字が、任意の数の異なる文字セットに属することができますが、各文字セット内で異なるコードポイントをもつのが一般的でしょう。文字セットの例にはascii、iso-8859-1、greek-iso8859-7、windows-1255が含まれます。文字セット内で文字に割り当てられるコードポイントは、Emacs内のバッファーや文字列内で使用されるコードポイントとは、通常異なります。

Emacsは、特別な文字セットをいくつか定義しています。文字セットunicodeは、Emacsコードポイントが0..#x10FFFFの範囲の、すべての文字セットを含みます。文字セットemacsは、すべてのASCII、および非ASCII文字を含みます。最後にeight-bit文字セットは、8ビットrawバイトを含みます。テキスト内でrawバイトを見つけたときに、Emacsはこれを使用します。

Function: charsetp object: objectは文字セットを命名するシンボルならt、それ以外はnilをリターンする。

Variable: charset-list: 値は、すべての定義済み文字セットの名前のリストである。

Function: charset-priority-list &optional highestp: この関数は、すべての定義済み文字セットの優先順にソートされたリストをリターンする。highestpが非nilなら、この関数はもっとも優先度の高い文字セット1つをリターンする。

Function: set-charset-priority &rest charsets: この関数は、charsetsをもっとも高い優先度の文字セットにする。

Function: char-charset character &optional restriction

この関数は、characterが属する文字セットで、もっとも優先度の高い文字セットの名前をリターンする。ただしASCII文字は例外であり、この関数は常にasciiをリターンする。

restrictionが非nilなら、それは検索する文字セットのリストであること。かわりにコーディングシステムも指定でき、その場合はそのコーディングシステムによりサポートされている必要がある(コーディングシステムを参照)。

Function: charset-plist charset: この関数は、文字セットcharsetのプロパティをリターンする。たとえcharsetがシンボルだったとしても、これはそのシンボルのプロパティリストと同じではない。文字セットプロパティにはドキュメント文字列、短い名前等、その文字セットに関する重要な情報が含まれる。

Function: put-charset-property charset propname value: この関数は、charsetのプロパティpropnameに、与えられたvalueをセットする。

Function: get-charset-property charset propname: この関数は、charsetのプロパティpropnameの値をリターンする。

Command: list-charset-chars charset: このコマンドは、文字セットcharset内の文字のリストを表示する。

Emacsは文字の内部的な表現と、その文字の特定の文字セット内でのコードポイントを相互に変換することができます。以下は、これらをサポートするための関数です。

Function: decode-char charset code-point: この関数は、charset内でcode-pointに割り当てられた文字を、Emacsの対応する文字にデコードして、それをリターンする。そのコードポイントの文字がcharsetに含まれなければ、値はnilである。code-pointがLisp整数(most-positive-fixnumを参照)に収まらない場合は、コンスセル(high . low)として指定できるかもしれない。ここでlowはその値の下位来る16ビット、highは上位16ビットである。

Function: encode-char char charset: この関数は、charset内で文字charに割り当てられた、コードポイントをリターンする。結果がLisp整数に収まらない場合は、上述のdecode-charの2つ目の引数のように、コンスセル(high . low)としてリターンされる。charsetがcharにたいするコードポイントをもたなければ、値はnilである。

以下の関数は、文字セット内の文字の一部、全くすべてにたいして、特定の関数を適用するのに便利です。

Function: map-charset-chars function charset &optional arg from-code to-code

charset内の文字にたいしてfunctionを呼び出す。functionは2つの引数で呼び出される。1つ目はコンスセル(from . to)で、fromとtoは文字セット内に含まれる文字の範囲である。argは、2つ目の引数としてfunctionに渡される。

デフォルトでは、functionに渡されるコードポイントの範囲にはcharset内のすべての文字が含まれるが、オプション引数from-codeおよびto-codeにより、それはcharsetの2つのコードポイント間にある文字範囲に制限される。from-codeまたはto-codeのいずれかがnilの場合のデフォルトは、charsetのコードポイントの最初または最後である。

33.8 文字セットのスキャン

特定の文字が、どの文字セットに属するか調べられると便利なときがあります。これの用途の1つは、どのコーディングシステム(コーディングシステムを参照)が問題となっているテキストすべてを表現可能か判断することです。他にも、そのテキストを表示するフォントの判断があります。

Function: charset-after &optional pos: この関数は、カレントバッファー内の位置posにある文字を含む、もっとも高い優先度の文字セットをリターンする。posが省略またはnilの場合のデフォルトは、ポイントのカレント値である。posが範囲外なら、値はnil。

Function: find-charset-region beg end &optional translation

この関数は、カレントバッファー内の位置begからendの間の文字を含む、もっとも優先度の高い文字セットのリストをリターンする。

オプション引数がtranslationは、テキストのスキャンに使用するための変換テーブルを指定する(文字の変換を参照)。これが非nilなら、リージョン内の各文字はそのテーブルを通じて変換され、リターンされる値にはバッファーの実際の文字ではなく、変換された文字が記述される。

Function: find-charset-string string &optional translation: この関数は、string内の文字を含む、もっとも優先度の高い文字セットのリストをリターンする。これはfind-charset-regionと似ているが、カレントバッファーの一部ではなくstringのコンテンツに適用される点が異なる。

33.9 文字の変換

変換テーブル(translation table)とは？文字から文字へのマッピングを指定する、文字テーブルです(文字テーブルを参照)。これらのテーブルはエンコーディング、デコーディング、および他の用地にも使用されます。独自に変換テーブルを指定するコーディングシステムも、いくつかあります。他のすべてのコーディングシステムに適用される、デフォルトの変換テーブルも存在します。

変換テーブルには、余分のスロットが2つあります。1つ目のスロットはnil、または逆の変換を処理する変換テーブルです。2つ目のスロットは、変換する文字シーケンスを照合する際の、最大文字数です(以下のmake-translation-table-from-alistの説明を参照)。

Function: make-translation-table &rest translations

この関数は、引数translationsにもとづいて、変換テーブルをリターンする。translationsの各要素は、(from . to)という形式のリストであること。これはfromからtoへの、文字の変換を指示する。

各引数内の引数とフォームは順に処理され、もし前のフォームですでにtoがたとえばto-altに変換されていれば、fromもto-altに変換される。

デコードを行う間、その変換テーブルの変換は、通常のデコーディングの結果の文字に適用されます。あるコーディングシステムがプロパティ:decode-translation-tableをもつなら、それは使用する変換テーブル、または順に適用するべき変換テーブルのリストを指定します(これはコーディングシステムの名前であるようなシンボルのプロパティではなく、coding-system-getがリターンするような、コーディングシステムのプロパティである。Basic Concepts of Coding Systemsを参照されたい)。最後に、もしstandard-translation-table-for-decodeが非nilなら、結果となる文字はそのテーブルにより変換されます。

エンコードを行う間は、その変換テーブルの変換はバッファー内の文字に適用され、変換結果は実際にエンコードされます。あるコーディングシステムがプロパティ:encode-translation-tableをもつなら、それは使用する変換テーブル、または順に適用するべき変換テーブルのリストを指定します。加えて、もし変数standard-translation-table-for-encodeが非nilなら、それは変換結果にたいして使用するべき変換テーブルを指定します。

Variable: standard-translation-table-for-decode: これはデコード用のデフォルトの変換テーブルである。あるコーディングシステムが独自に変換テーブルを指定する場合、この変数の値が非nilなら、それら独自のテーブル適用後に、この変数の変換テーブルが適用される。

Variable: standard-translation-table-for-encode: これはエンコード用のデフォルトの変換テーブルである。あるコーディングシステムが独自に変換テーブルを指定する場合、この変数の値が非nilなら、それら独自のテーブル適用後に、この変数の変換テーブルが適用される。

Variable: translation-table-for-input

自己ソウニュ文字は、挿入前にこの変換テーブルを通じて変換が行われる。検索コマンドも、バッファー内の内容とより信頼性のある比較ができるように、このテーブルを通じて入力を変換する。

この変数は、セット時に自動的にバッファーローカルになる。

Function: make-translation-table-from-vector vec

この関数は、バイト(値は0から#xFF)から文字にマップする256要素の配列であるようなvecから作成した変換テーブルをリターンする。未変換のバイトにたいする要素は、nilかもしれない。リターンされるテーブルは、余分な1つ目のスロットにそのマッピングを保持する変換テーブル、2つ目の余分なスロットに値1をもつ。

この関数は、各バイトを特定の文字にマップするような、プライベートなコーディングシステムを簡単に作成する手段を提供する。define-coding-systemのprops引数のプロパティ:decode-translation-tableと:encode-translation-tableに、リターンされるテーブルと、逆変換テーブルを指定できる。

Function: make-translation-table-from-alist alist: この関数はmake-translation-tableと似ているが、シンプルな1体1の変換テーブルではなく、より複雑な変換テーブルをリターンする。alistの各要素は(from . to)という形式をもち、ここでfromおよびtoは、文字または文字シーケンスを指定するベクターである。fromが文字なら、その文字はto(文字または文字シーケンス)に変換される。fromが文字のベクターならそのシーケンスはtoに変換される。リターンされるテーブルは、1つ目の余分なスロットに逆のマッピングを行う変換テーブル、2つ目の余分なスロットには文字シーケンスfromすべての最大長をもつ。

33.10 コーディングシステム

Emacsがファイルにたいして読み書きを行う際、およびEmacsがサブプロセスとテキストの送受信を行う際、通常は特定のコーディングシステム(coding system)の指定にしたがって文字コード変換および行末変換を行います。

コーディングシステムの定義は難解な問題であり、ここには記述しません。

33.10.1 コーディングシステムの基本概念		基本的な概念。
33.10.2 エンコーディングとI/O		ファイル入出力関数がコーディングシステムを扱う方法。
33.10.3 Lispでのコーディングシステム		コーディングシステム名を処理する関数。
33.10.4 ユーザー選択のコーディングシステム		ユーザーにコーディングシステムの選択を求める。
33.10.5 デフォルトのコーディングシステム		デフォルトの選択の制御。
33.10.6 単一の操作にたいするコーディングシステムの指定		単一ファイル処理にたいして特定のコーディングシステムを要求する。
33.10.7 明示的なエンコードとデコード		入出力を伴わないテキストのエンコードおよびデコード。
33.10.8 端末I/Oのエンコーディング		端末入出力にたいするエンコーディングの使用。

33.10.1 コーディングシステムの基本概念

文字コード変換(character code conversion)により、Emacs内部で使用される文字の内部表現と他のエンコーディングの間で、変換が行われます。Emacsは多くの異なるエンコーディングをサポートしており、それらは双方向に変換が可能です。たとえばLatin 1、Latin 2、Latin 3、Latin 4、Latin 5、およびいくつかのISO 2022の変種等のようなエンコーディングにたいして、テキストを双方向に変換できます。あるケースにおいては、同じ文字にたいしてEmacsは複数のエンコーディング候補をサポートします。たとえばキリル(ロシア語)のアルファベットにたいしてはISO、Alternativnyj、KOI8のように3つにコーディングシステムが存在します。

Every coding system specifies a particular set of character code conversions, but the coding system undecided is special: it leaves the choice unspecified, to be chosen heuristically for each file, based on the file’s data. The coding system prefer-utf-8 is like undecided, but it prefers to choose utf-8 when possible.

一般的に、コーディングシステムは可逆的な同一性を保証しません。あるコーディングシステムを使用してバイトシーケンスをデコードしてから、同じコーディングシステムで結果テキストをエンコードしても、異なるバイトシーケンスが生成される可能性があります。しかし、デコードされたオリジナルのバイトシーケンスとなることを保証するコーディングシステムもいくつかあります。以下にいくつかの例を挙げます:

iso-8859-1、utf-8、big5、shift_jis、euc-jp

バッファーテキストのエンコードと結果のデコードでも、オリジナルテキストの再生成に失敗する可能性があります。たとえば、その文字をサポートしないコーディングシステムで文字をエンコードした場合の結果は予測できず、したがって同じコーディングシステムを使用してそれをデコードしても、異なるテキストが生成されるでしょう。現在のところ、Emacsは未サポート文字のエンコーディングによる結果をエラーとして報告できません。

End of line conversion handles three different conventions used on various systems for representing end of line in files. The Unix convention, used on GNU and Unix systems, is to use the linefeed character (also called newline). The DOS convention, used on MS-Windows and MS-DOS systems, is to use a carriage return and a linefeed at the end of a line. The Mac convention is to use just carriage return. (This was the convention used in Classic Mac OS.)

latin-1のようなベースコーディングシステム(base coding systems: 基本コーディングシステム)では、データにもとづいて選択されるよう、行末変換は未指定となっています。latin-1-unix、latin-1-dos、latin-1-macのようなバリアントコーディングシステム(variant coding systems: 変種コーディングシステム)では、行末変換を明示的に指定します。ほとんどのベースコーディングシステムは‘-unix’、‘-dos’、‘-mac’を追加した形式の、3つの対応する変種をもちます。

raw-textは、文字コード変換を抑制して、このコーディングシステムでvisitされたバッファーがユニバイトバッファーとなる点において、特殊なコーディングシステムです。歴史的な理由により、このコーディングシステムによりユニバイトおよびマルチバイト両方のテキストを保存できます。マルチバイトテキストのエンコードにraw-textを使用した際は、1文字コード変換を行います。8ビット文字は、1バイトの外部表現に変換されます。raw-textは通常のようにデータにより判断できるように行末変換を指定せず、通常のように行末変換を指定する3つの変種をもちます。

no-conversion(とエイリアスのbinary)は、raw-text-unixと等価です。これは文字コードおよび行末にたいする変換をいずれもしてくださいしません。

The coding system utf-8-emacs specifies that the data is represented in the internal Emacs encoding (see section テキストの表現方法). This is like raw-text in that no code conversion happens, but different in that the result is multibyte data. The name emacs-internal is an alias for utf-8-emacs-unix (so it forces no conversion of end-of-line, unlike utf-8-emacs, which can decode all 3 kinds of end-of-line conventions).

Function: coding-system-get coding-system property

この関数は、コーディングシステムcoding-systemの、指定されたプロパティをリターンする。コーディングシステムのプロパティのほとんどは内部的な目的のために存在するが、:mime-charsetについては有用と思うかもしれない。このプロパティの値は、そのコーディングシステムが読み書きできる文字コードにたいしてMIME内で使用される名前である。以下に例を示す:

(coding-system-get 'iso-latin-1 :mime-charset)
     ⇒ iso-8859-1
(coding-system-get 'iso-2022-cn :mime-charset)
     ⇒ iso-2022-cn
(coding-system-get 'cyrillic-koi8 :mime-charset)
     ⇒ koi8-r

:mime-charsetプロパティの値は、そのコーディングシステムにたいするエイリアスとしても定義されている。

Function: coding-system-aliases coding-system: この関数は、coding-systemのエイリアスのリストをリターンする。

33.10.2 エンコーディングとI/O

コーディングシステムの主な目的は、ファイルの読み込みと書き込みへの使用です。関数insert-file-contentsはファイルデータのデコードにコーディングシステムを使用し、write-regionはバッファーコンテンツのエンコードにコーディングシステムを使用します。

You can specify the coding system to use either explicitly (see section 単一の操作にたいするコーディングシステムの指定), or implicitly using a default mechanism (see section デフォルトのコーディングシステム). But these methods may not completely specify what to do. For example, they may choose a coding system such as undecided which leaves the character code conversion to be determined from the data. In these cases, the I/O operation finishes the job of choosing a coding system. Very often you will want to find out afterwards which coding system was chosen.

Variable: buffer-file-coding-system

このバッファーローカル変数は、バッファーの保存、およびwrite-regionによるバッファー部分のファイルへの書き出しに使用されるコーディングシステムを記録する。書き込まれるテキストが、この変数で指定されたコーディングシステムを使用して安全にエンコードできない場合、これらの操作は関数select-safe-coding-systemを呼び出すことにより、代替となるエンコーディングを選択する(ユーザー選択のコーディングシステムを参照)。異なるエンコーディングの選択が、ユーザーによるコーディングシステムの指定を要するなら、buffer-file-coding-systemは新たに選択されたコーディングシステムに更新される。

buffer-file-coding-systemは、サブプロセスへのテキスト送信に影響しない。

Variable: save-buffer-coding-system

この変数は、(buffer-file-coding-systemをオーバーライドして)バッファーを保存するためのコーディングシステムを指定する。これはwrite-regionには使用されないことに注意。

あるコマンドがバッファーを保存するためにbuffer-file-coding-system(またはsave-buffer-coding-system)の使用を開始して、そのコーディングシステムがバッファー内の実際のテキストを処理できなければ、(select-safe-coding-systemを呼び出すことにより)そのコマンドは他のコーディングシステムの選択をユーザーに求める。これが発生した後は、コマンドはユーザー指定のコーディングシステムを表すために、buffer-file-coding-systemの更新も行う。

Variable: last-coding-system-used

ファイルおよびサブプロセスにたいするI/O操作は、使用したコーディングシステムの名前を、この変数にセットする。明示的にエンコードとデコードを行う関数(明示的なエンコードとデコードを参照)も、この変数をセットする。

警告: サブプロセス出力の受信によりこの変数がセットされるため、この変数はEmacsがwaitしているとくは常に変更され得る。したがって、興味対象となる値を格納する関数呼び出し後は、間を空けずにその値をコピーするべきである。

変数selection-coding-systemはウィンドウシステムにたいして、選択(selection)をエンコードする方法を指定します。ウィンドウシステムによる選択を参照してください。

Variable: file-name-coding-system: 変数file-name-coding-systemは、ファイル名のエンコーディングに使用するコーディングシステムを指定する。Emacsは、すべてのファイル操作にたいして、ファイル名のエンコードにそのコーディングシステムを使用する。file-name-coding-systemがnilなら、Emacsは選択された言語環境(language environment)により決定された、デフォルトのコーディングシステムを使用する。デフォルト言語環境では、ファイル名に含まれるすべての非ASCII文字は、特別にエンコードされない。これらはEmacsの内部表現を使用して、ファイルシステム内で表される。

警告: Emacsのセッション中にfile-name-coding-system(または言語環境)を変更した場合、以前のコーディングシステムを使用してエンコードされた名前をもつファイルをvisitしていると、新たなコーディングシステムでは異なるように扱われるので、問題が発生し得る。これらのvisitされたファイル名でこれらのバッファーの保存を試みると、保存により間違ったファイル名が使用されるか、エラーとなるかもしれない。そのような問題が発生したら、そのバッファーにたいして新たなファイル名を指定するために、C-x C-wを使用すること。

Windows 2000以降では、EmacsはOSに渡すファイル名にデフォルトでUnicode APIを使用するため、file-name-coding-systemの値は大部分が無視される。Lispレベルでファイル名のエンコードまたはデコードを必要とするLispアプリケーションは、system-typeがwindows-ntのときは、utf-8をコーディングシステムに使用するべきである。UTF-8でエンコードされたファイル名から、OSと対話するために適したエンコーディングへの変換は、Emacsにより内部的に処理される。

33.10.3 Lispでのコーディングシステム

以下はコーディングシステムと連携するLisp機能です:

Function: coding-system-list &optional base-only: この関数は、すべてのコーディングシステムの名前(シンボル)をリターンする。base-onlyが非nilなら、値にはベースコーディングシステムだけが含まれる。それ以外ならエイリアス、およびバリアントコーディングシステムも同様に含まれる。

Function: coding-system-p object: この関数は、objectがコーディングシステムの名前、またはnilなら、tをリターンする。

Function: check-coding-system coding-system: この関数は、coding-systemの有効性をチェックする。有効ならcoding-systemをリターンする。coding-systemがnilなら、この関数はnilをリターンする。それ以外の値にたいしては、error-symbolがcoding-system-errorであるようなエラーをシグナルする(signalを参照)。

Function: coding-system-eol-type coding-system

この関数は、行末(eolとも言う)をcoding-systemで使用されるタイプに変換する。coding-systemが特定のeol変換を指定する場合、リターン値は0、1、2で、それらは順にunix、dos、macを意味する。coding-systemが明示的にeol変換を指定しなければ、リターン値は以下のようにそれぞれが可能なeol変換タイプをもつようなコーディングシステムのベクターである:

(coding-system-eol-type 'latin-1)
     ⇒ [latin-1-unix latin-1-dos latin-1-mac]

この関数がベクターをリターンしたら、Emacsはテキストのエンコードやデコードプロセスの一部として、使用するeol変換を決定するだろう。デコードでは、テキストの行末フォーマットは自動検知され、eol変換はそれに適合するようセットされる(DOSスタイルのCRLFフォーマットは暗黙でeol変換にdosをセットする)。エンコードにたいしては、適切なデフォルトコーディングシステム(buffer-file-coding-systemにたいするbuffer-file-coding-systemのデフォルト値)、または配下にあるプラットフォームにたいして適切なデフォルトeol変換が採用される。

Function: coding-system-change-eol-conversion coding-system eol-type

この関数は、coding-systemと類似するが、eol-typeで指定されたeol変換の異なるコーディングシステムをリターンする。eol-typeはunix、dos、mac、またはnilであること。これがnilなら、リターンされるコーディングシステムは、データのeol変換により決定される。

eol-typeはunix、dos、macを意味する0、1、2でもよい。

Function: coding-system-change-text-conversion eol-coding text-coding: この関数は、eol-codingの行末変換と、text-codingのテキスト変換を使用するコーディングシステムをリターンする。text-codingがnilなら、これはundecided、またはeol-codingに対応するバリアントの1つをリターンする。

Function: find-coding-systems-region from to

この関数は、fromとtoの間のテキストのエンコードに使用可能な、コーディングシステムのリストをリターンする。このリスト内のすべてのリストは、そのテキスト範囲内にあるすべてのマルチバイト文字を、安全にエンコードできる。

そのテキストがマルチバイト文字を含まれなければ、この関数はリスト(undecided)をリターンする。

Function: find-coding-systems-string string: この関数は、stringのテキストのエンコードに使用可能な、コーディングシステムのリストをリターンする。このリスト内のすべてのリストは、stringにあるすべてのマルチバイト文字を、安全にエンコードできる。そのテキストがマルチバイト文字を含まれなければ、この関数はリスト(undecided)をリターンする。

Function: find-coding-systems-for-charsets charsets: この関数は、リストcharsets内のすべての文字セットのエンコードに使用可能な、コーディングシステムのリストをリターンする。

Function: check-coding-systems-region start end coding-system-list

この関数は、リストcoding-system-list内のコーディングシステムが、startとendの間のリージョン内にあるすべての文字をエンコード可能かどうかをチェックする。このリスト内のすべてのコーディングシステムが指定されたテキストをエンコード可能なら、この関数はnilをリターンする。ある文字をエンコードできないコーディングシステムがある場合は、各要素が(coding-system1 pos1 pos2 …)という形式のalistが値となる。これはcoding-system1が、バッファーの位置pos1、pos2、...にある文字をエンコードできないことを意味する。

startは文字列かもしれず、その場合endは無視され、リターン値はバッファー位置のかわりに文字列のインデックスを参照することになる。

Function: detect-coding-region start end &optional highest

この関数は、startからendのテキストのデコードに適したコーディングシステムを選択する。このテキストはバイトシーケンス、すなわちユニバイトテキスト、ASCIIのみのマルチバイトテキスト、8ビット文字のシーケンスであること(明示的なエンコードとデコードを参照)。

この関数は通常はスキャンしたテキストのデコーディングを処理可能な、コーディングシステムのリストをリターンする。これらのコーディングシステムは優先度降順でリストされる。しかしhighestが非nilなら、リターン値はもっとも高い優先度のコーディングシステムただ1つとなる。

リージョンにISO-2022のESCのようなISO-2022制御文字を除いてASCII文字だけが含まれる場合、値はundecided、(undecided)、またはテキストから推論可能ならeol変換を指定するバリアントとなる。

リージョンにnullバイトが含まれる場合は、あるコーディングシステムによりエンコードされたテキストがリージョン内に含まれる場合でも、値はno-conversionとなる。

Function: detect-coding-string string &optional highest: この関数はdetect-coding-regionと似ているが、バッファー内のバイトのかわりにstringのコンテンツを処理する点が異なる。

Variable: inhibit-null-byte-detection: If this variable has a non-nil value, null bytes are ignored when detecting the encoding of a region or a string. This allows the encoding of text that contains null bytes to be correctly detected, such as Info files with Index nodes.

Variable: inhibit-iso-escape-detection: この変数が非nil値をもつなら、リージョンや文字列のエンコーディング検出時に、ISO-2022エスケープシーケンスを無視する。その結果、これまでいくつかのISO-2022エンコーディングにおいてエンコード済みと検出されていたテキストがなくなり、バッファー内ですべてのエスケープシーケンスが可視になる。警告: この変数の使用には特に注意を払うこと。なぜならEmacsディストリビューション内で多くのファイルがISO-2022エンコーディングを使用するからである。

Function: coding-system-charset-list coding-system

この関数は、coding-systemがサポートする文字セット(文字セットを参照)のリストをリターンする。リストすべき文字セットを非常に多くサポートするいくつかのコーディングシステムでは、特別な値がリストされる:

coding-systemがすべてのEmacs文字をサポートするなら、値は(emacs)。
coding-systemがすべてのUnicode文字をサポートするなら、値は(unicode)。
coding-systemがすべてのISO-2022文字をサポートするなら、値はiso-2022。
coding-systemがEmacsバージョン21(Unicodeサポートの内部的な実装以前)で使用される内部的コーディングシステム内のすべての文字をサポートするなら、値はemacs-mule。

サブプロセスへの入出力に使用されるコーディングシステムのチェックやセットの方法については、Process Information、特に関数process-coding-systemおよびset-process-coding-systemの説明を参照してください。

33.10.4 ユーザー選択のコーディングシステム

Function: select-safe-coding-system from to &optional default-coding-system accept-default-p file

この関数は、指定されたテキストをエンコードするために、必要ならユーザーに選択を求めて、コーディングシステムを選択する。指定されるテキストは、通常はカレントバッファーのfromとtoの間のテキストである。fromが文字列なら、その文字列はエンコードするテキストを指定し、toは無視される。

指定されたテキストにrawバイト(テキストの表現方法を参照)が含まれる場合、select-safe-coding-systemはそのエンコーディングにraw-textを提案する。

default-coding-systemが非nilなら、それは試行すべき最初のコーディングシステムである。それがテキストを処理できるなら、select-safe-coding-systemはそのコーディングシステムをリターンする。これはコーディングシステムのリストの可能性もある。その場合、この関数はそれらを1つずつ試みる。それらをすべて試した後に、(undecided以外なら)カレントバッファーのbuffer-file-coding-systemの値、次にbuffer-file-coding-systemのデフォルト値、最後にユーザーがもっとも好むコーディングシステム(コマンドprefer-coding-systemでセットできる最優先されるコーディングシステム)を試みる(Recognizing Coding Systems in The GNU Emacs Manualを参照)。

これらのうちいずれかのコーディングシステムが指定されたテキストすべてを安全にエンコード可能なら、select-safe-coding-systemはそれを選択およびリターンする。それ以外なら、コーディングシステムのリストからすべてのテキストをエンコードできるコーディングシステムの選択をユーザーに求めて、ユーザーの選択をリターンする。

default-coding-system can also be a list whose first element is t and whose other elements are coding systems. Then, if no coding system in the list can handle the text, select-safe-coding-system queries the user immediately, without trying any of the three alternatives described above. This is handy for checking only the coding systems in the list.

The optional argument accept-default-p determines whether a coding system selected without user interaction is acceptable. If it’s omitted or nil, such a silent selection is always acceptable. If it is non-nil, it should be a function; select-safe-coding-system calls this function with one argument, the base coding system of the selected coding system. If the function returns nil, select-safe-coding-system rejects the silently selected coding system, and asks the user to select a coding system from a list of possible candidates.

変数select-safe-coding-system-accept-defaultf-pが非nilなら、それは1つの引数をとる関数であること。これはaccept-default-p引数に与えられた値をオーバーライドすることにより、accept-default-pのかわりに使用される。

最後のステップとして、選択されたコーディングシステムをリターンする前に、select-safe-coding-systemは、もしリージョンのコンテンツがファイルから読み込まれたものだったとしたなら選択されたであろうコーディングシステムと、そのコーディングシステムが一致するかどうかをチェックする(異なるなら、その後の再visitと編集でファイル内のデータ汚染が起こり得る)。通常、select-safe-coding-systemはこの目的のためのファイルとしてbuffer-file-nameを使用するが、fileが非nilなら、かわりにそのファイルをかわりに使用する(これはwrite-region、および類似の関数に関連し得る)。明らかな不一致が検出された場合、select-safe-coding-systemはそのコーディングシステムを選択する前に、ユーザーに問い合わせる。

Variable: select-safe-coding-system-function: This variable names the function to be called to request the user to select a proper coding system for encoding text when the default coding system for an output operation cannot safely encode that text. The default value of this variable is select-safe-coding-system. Emacs primitives that write text to files, such as write-region, or send text to other processes, such as process-send-region, normally call the value of this variable, unless coding-system-for-write is bound to a non-nil value (see section 単一の操作にたいするコーディングシステムの指定).

以下の2つの関数は、補完つきでユーザーにコーディングシステムの選択を求めるために使用できます。補完を参照してください。

Function: read-coding-system prompt &optional default: この関数は、文字列promptをプロンプトにミニバッファーを使用してコーディングシステムを読み取り、そのコーディングシステムの名前をシンボルとしてリターンする。defaultは、ユーザーの入力が空の場合にリターンするべきコーディングシステムを指定する。これはシンボルまたは文字列であること。

Function: read-non-nil-coding-system prompt: この関数は、文字列promptをプロンプトにミニバッファーを使用してコーディングシステムを読み取り、そのコーディングシステムの名前をシンボルとしてリターンする。ユーザーが空の入力を試みると、再度ユーザーに問い合わせを行う。コーディングシステムを参照のこと。

33.10.5 デフォルトのコーディングシステム

このセクションでは、特定のファイルや特定のサブプロセス実行時のデフォルトコーディングシステムを指定する変数、およびそれらへアクセスするためのI/O処理が使用する関数について説明します。

これらの変数は、希望するデフォルトにそれらすべてを一度セットして、その後は再びそれを変更しないというアイデアにもとづいています。Lispプログラム内の特定の処理で特定のコーディングシステムを指定するために、これらの変数を変更しないでください。かわりにcoding-system-for-readおよびcoding-system-for-writeを使用して、それらをオーバーライドしてください(単一の操作にたいするコーディングシステムの指定を参照)。

User Option: auto-coding-regexp-alist: This variable is an alist of text patterns and corresponding coding systems. Each element has the form (regexp . coding-system); a file whose first few kilobytes match regexp is decoded with coding-system when its contents are read into a buffer. The settings in this alist take priority over coding: tags in the files and the contents of file-coding-system-alist (see below). The default value is set so that Emacs automatically recognizes mail files in Babyl format and reads them with no code conversions.

User Option: file-coding-system-alist

この変数は、特定のファイルの読み書きに使用するコーディングシステムを指定するalistである。要素はそれぞれ(pattern . coding)という形式をもち、patternは特定のファイル名にマッチする正規表現である。この要素はpatternにマッチするファイル名に適用される。

要素のCDRとなるcodingはコーディングシステム、2つのコーディングシステムを含むコンスセル、または関数名(関数定義をもつシンボル)であること。codingがコーディングシステムなら、そのコーディングシステムはファイルの読み込みと書き込みの両方で使用される。codingが2つのコーディングシステムを含むコンスセルなら、CARはデコード用のコーディングシステム、CDRはエンコード用のコーディングシステムを指定する。

codingが関数名なら、それはfind-operation-coding-systemに渡されたすべての引数からなるリストを唯一の引数とする関数であること。これはコーディングシステム、または2つのコーディングシステムを含むコンスセルをリターンしなければならない。この値は上記と同じ意味をもつ。

coding(または上記関数のリターン値)がundecidedなら、通常のコード検出が行われる。

User Option: auto-coding-alist: この変数は、特定のファイルの読み書きに使用するコーディングシステムを指定するalistである。この変数の形式はfile-coding-system-alistの形式と似ているが、後者と異なるのは、この変数がファイル内のcoding:タグより優先されることである。

Variable: process-coding-system-alist: この変数は、何のプログラムがサブプロセス内で実行中かによって、そのサブプロセスにたいしてどのコーディングシステムを使用するかを指定するalistである。これはfile-coding-system-alistと同じように機能するが、patternがそのサブプロセスを開始するために使用されたプログラム名にたいしてマッチされる点が異なる。コーディングシステム、またはalist内で指定されたコーディングシステムは、そのサブプロセスへのI/Oに使用されるコーディングシステムの初期化に使用されるが、set-process-coding-systemを使用して後から他のコーディングシステムを指定できる。

警告: データからコーディングシステムを判断するundecidedのようなコーディングシステムは、非同期のサブプロセスでは完全な信頼性をもって機能はしない。これはEmacsが非同期サブプロセスの出力を、到着によりバッチ処理するためである。そのコーディングシステムが文字コード変換、または行末変換を未指定にしておくと、Emacsは一度に1バッチから正しい変換の検出を試みなければならず、これは常に機能するとは限らない。

したがって非同期サブプロセスでは、可能なら文字コード変換と行末変換の両方を判断するコーディングシステム、つまりundecidedやlatin-1ではなくlatin-1-unixのようなコーディングシステムを使用すること。

Variable: network-coding-system-alist: この変数は、ネットワークストリームに使用するコーディングシステムを指定するalistである。これはfile-coding-system-alistと同じように機能するが、要素内のpatternがポート番号、または正規表現かもしれない点が異なる。正規表現なら、そのネットワークストリームのオープンに使用されたネットワークサービス名にたいしてマッチされる。

Variable: default-process-coding-system

この変数は、他に何を行うか指定されていない際に、サブプロセス(とネットワークストリーム)への入出力に使用するコーディングシステムを指定する。

値は、(input-coding . output-coding)という形式のコンスセルであること。ここでinput-codingはサブプロセスからの入力、output-codingはサブプロセスへの出力に適用される。

User Option: auto-coding-functions

この変数は、ファイルのデコードされていないコンテンツにもとづいて、ファイルにたいするコーディングシステムの判断を試みる関数のリストを保持する。

このリスト内の各関数は、カレントバッファー内のテキストを調べるように、ただしいいかなる方法にせよそれを変更しないよう記述されるべきである。そのバッファーは、ファイルの一部であるデコードされていないテキストを含むだろう。各関数はポイントを始点に何文字を調べる可を告げる、唯一の引数sizeをとること。関数が、そのファイルにたいするコーディングシステムの決定に成功したら、そのコーディングシステムをリターンすること。それ以外はnilをリターンするべきである。

ファイルに‘coding:’タグがある場合は、それが優先されるので、これらの関数が呼び出されることはないだろう。

Function: find-auto-coding filename size

この関数は、filenameに適するコーディングシステムの判定を試みる。これは、上記で説明した変数により指定されたルールのいずれかにマッチするまで、それらの変数を順に使用して、ファイルをvisitするバッファーを調べる。そして(coding . source)という形式のコンスセルをリターンする。ここでcodingは使用するコーディングシステム、sourceははauto-coding-alist、auto-coding-regexp-alist、:coding、auto-coding-functionsのいずれかであるようなシンボルで、マッチングルールとして供されるルールを示す。値:codingは、ファイル内のcoding:タグによりコーディングシステムが指定されたことを意味する(coding tag in The GNU Emacs Manualを参照)。マッチングルールを調べる順序はauto-coding-alist、auto-coding-regexp-alist、coding:、auto-coding-functionsの順である。マッチングルールが見つからなければ、この関数はnilをリターンする。

2つ目の引数sizeは、ポイントの後のテキストの文字単位のサイズである。この関数は、ポイントの後のsize文字のテキストだけを調べる。coding:タグが置かれる箇所としてはファイルの先頭2行が考えられる箇所の1つなので、通常はバッファーの先頭位置で、この関数を呼び出すべきである。その場合、sizeはそのバッファーのサイズであること。

Function: set-auto-coding filename size: この関数は、ファイルfilenameに適するコーディングシステムをリターンする。これはコーディングシステムを探すために、find-auto-codingを使用する。コーディングシステムを決定できなかったら、この関数はnilをリターンする。引数sizeの意味は、find-auto-codingと同様。

Function: find-operation-coding-system operation &rest arguments

この関数は、operationをargumentsで行う際に、(デフォルトで)使用するコーディングシステムをリターンする。値は以下の形式である:

(decoding-system . encoding-system)

1つ目の要素decoding-systemはデコード(operationがデコードを行う場合)、encoding-systemはエンコード(operationがエンコードを行う場合)に使用するコーディングシステムである。

引数operationはシンボルでwrite-region、start-process、call-process、call-process-region、insert-file-contents、open-network-streamのいずれかであること。これらは文字コード変換と行末変換を行うことができる、EmacsのI/Oプリミティブの名前である。

残りの引数は、対応するI/Oプリミティブに与えられる引数と同じであること。そのプリミティブに応じて、これらの引数のうち1つがターゲットとして選択される。たとえばoperationがファイルI/Oなら、ファイル名を指定する引数がターゲットである。サブプロセス用のプリミティブでは、プロセス名がターゲットになる。open-network-streamでは、サービス名またはポート番号がターゲットである。

operationに応じて、この関数はfile-coding-system-alist、process-coding-system-alist、network-coding-system-alistの中からターゲットを探す。このalist内でターゲットが見つかったら、find-operation-coding-systemはalist内のassociation(連想: キーと連想値からなるコンスセル)をリターンし、それ以外はnilをリターンする。

operationがinsert-file-contentsなら、ターゲットに対応する引数は、(filename . buffer)という形式のコンスセルだろう。この場合、filenameはfile-coding-system-alist内で照合されるファイル名であり、bufferはそのファイルの(デコードされていない)コンテンツを含むバッファーである。file-coding-system-alistがこのファイルにたいして呼び出す関数を指定していて、かつ(通常行われるように)ファイルのコンテンツを調べる必要があるなら、ファイルを読み込むかわりにbufferのコンテンツを調べるべきである。

33.10.6 単一の操作にたいするコーディングシステムの指定

変数coding-system-for-readおよび/またはcoding-system-for-writeをバインドすることにより、特定の操作にたいしてコーディングシステムを指定できます。

Variable: coding-system-for-read

この変数が非nilなら、それはファイルの読み込み、または同期サブプロセスプロセスからの入力にたいして使用する、コーディングシステムを指定する。

これは非同期サブプロセスやネットワークストリームにも適用されるが、その方法は異なる。サブプロセス開始時、またはネットワークストリームオープン時のcoding-system-for-readの値は、サブプロセスまたはネットワークストリームにたいして入力のデコードメソッドを指定する。そのサブプロセスまたはネットワークストリームにたいして、それがオーバーライドされるまで、それが使用され続ける。

特定のI/O操作にたいしてletでバインドするのが、この変数の正しい使い方である。この変数のグローバル値は常にnilであり、他の値にグローバルにセットするべきではない。以下は、この変数の正しい使用例である:

;; 文字コード変換なしでファイルを読み込む
(let ((coding-system-for-read 'no-conversion))
  (insert-file-contents filename))

この変数の値が非nilのときはfile-coding-system-alist、process-coding-system-alist、network-coding-system-alistを含む、入力にたいして使用するコーディングシステムを指定するすべてのメソッドより、この変数が優先される。

Variable: coding-system-for-write

This works much like coding-system-for-read, except that it applies to output rather than input. It affects writing to files, as well as sending output to subprocesses and net connections. It also applies to encoding command-line arguments with which Emacs invokes subprocesses.

単一の操作がcall-process-regionやstart-processのように、入力と出力の両方を行う際は、coding-system-for-readとcoding-system-for-writeの両方がそれに影響する。

Variable: coding-system-require-warning: Binding coding-system-for-write to a non-nil value prevents output primitives from calling the function specified by select-safe-coding-system-function (see section ユーザー選択のコーディングシステム). This is because C-x RET c (universal-coding-system-argument) works by binding coding-system-for-write, and Emacs should obey user selection. If a Lisp program binds coding-system-for-write to a value that might not be safe for encoding the text to be written, it can also bind coding-system-require-warning to a non-nil value, which will force the output primitives to check the encoding by calling the value of select-safe-coding-system-function even though coding-system-for-write is non-nil. Alternatively, call select-safe-coding-system explicitly before using the specified encoding.

User Option: inhibit-eol-conversion: この変数が非nilなら、どのコーディングシステムが指定されたかに関わらず、行末変換は何も行われない。これはEmacsすべてのI/Oおよびサブプロセスにたいするプリミティブ、および明示的なエンコード関数(明示的なエンコードとデコードを参照)とデコード関数に適用される。

ある操作にたいして、固定された1つのコーディングシステムではなく、複数のコーディングシステムを選択する必要があることが、ときおりあります。Emacsでは、使用するコーディングシステムにたいして優先順位を指定できます。これは、find-coding-systems-region(Lispでのコーディングシステムを参照)のような関数によりリターンされるコーディングシステムのリストのソート順に影響します。

Function: coding-system-priority-list &optional highestp: この関数は、コーディングシステムのカレント優先順に、コーディングシステムのリストをリターンする。オプション引数highestpが非nilなら、それはもっとも高い優先度のコーディングシステムだけをリターンすることを意味する。

Function: set-coding-system-priority &rest coding-systems: この関数は、コーディングシステムの優先リストの先頭にcoding-systemsを置き、それらを他のコーディングシステムすべてより高い優先度とする。

Macro: with-coding-priority coding-systems &rest body…: このマクロは、coding-systemsをコーディングシステム優先リスト先頭に置いて、progn(prognを参照)が行うように、bodyを実行する。coding-systemsは、body実行中に選択するコーディングシステムのリストであること。

33.10.7 明示的なエンコードとデコード

Emacs内外へテキストを転送するすべての操作は、そのテキストをエンコードまたはデコードする能力をもっています。このセクション内の関数を使用して、テキストを明示的にエンコードあるいはデコードすることもできます。

エンコード結果およびデコーディングへの入力は、通常のテキストではありません。これらは理論的には一連のバイト値から構成され、すなわち一連のASCII文字と8ビット文字から構成されます。ユニバイトのバッファーおよび文字列では、これらの文字は0から#xFF(255)の範囲のコードをもちます。マルチバイトのバッファーおよび文字列では、8ビット文字は#xFFより大きい文字コードをもちますが(テキストの表現方法を参照)、そのようなテキストのエンコードやデコード時、Emacsは透過的にそれらを単一バイト値に変換します。

コンテンツを明示的にデコードできるように、バイトシーケンスとしてバッファーにファイルを読み込むには、insert-file-contents-literally(ファイルの読み込みを参照)を使用するのが通常の方法です。あるいはfind-file-noselectでファイルをvisitする際、引数rawfileに非nilを指定することもできます。これらのメソッドの結果は、ユニバイトバッファーになります。

テキストを明示的にエンコードした結果であるバイトシーケンスは、たとえばそれをwrite-region(see section ファイルの書き込み)で書き込み、coding-system-for-writeをno-conversionにバインドすることによりエンコードを抑制する等、それをファイルまたはプロセスへコピーするのが、通常の使い方です。

以下は、エンコードまたはデコードを明示的に行う関数です。エンコード関数とはバイトシーケンスを生成し、デコード関数とはバイトシーケンスを操作する関数のことを意味します。これらの関数はすべて、テキストプロパティを破棄します。これらは、自身が使用したコーディングシステムを、正確にlast-coding-system-usedすることも行います。

Command: encode-coding-region start end coding-system &optional destination

このコマンドは、startからendのテキストを、コーディングシステムcoding-systemでエンコードする。通常、バッファー内の元テキストはエンコードされたテキストで置き換えられるが、オプション引数destinationでそれを変更できる。destinationがバッファーなら、エンコードされたテキストはそのバッファーのポイントの後に挿入される(ポイントは移動しない)。tなら、このコマンドはエンコードされたテキストを挿入せずに、ユニバイトとしてリターンする。

エンコードされたテキストが何らかのバッファーに挿入された場合、このコマンドはエンコードされたテキストの長さをリターンする。

エンコードされた結果は理論的にはバイトシーケンスだが、バッファーが以前マルチバイトだったならマルチバイトのまま留まり、すべての8ビットのバイトはマルチバイト表現に変換される(テキストの表現方法を参照)。

期待しない結果となる恐れがあるので、テキストのエンコードする際は、coding-systemにundecidedを使用してはならない。coding-systemにたいして自明な適値が存在しなければ、適切なエンコードを提案させるために、かわりにselect-safe-coding-systemを使用すること(select-safe-coding-systemを参照)。

Function: encode-coding-string string coding-system &optional nocopy buffer: この関数は、コーディングシステムcoding-systemで、string内のテキストをエンコードする。これはエンコードされたテキストを含む新たな文字列をリターンするが、nocopyが非nilの場合、些細なエンコード処理なら、この関数はstring自身をリターンする。エンコード結果はユニバイト文字列である。

Command: decode-coding-region start end coding-system &optional destination

このコマンドは、コーディングシステムcoding-systemで、startからendのテキストをデコードする。明示的なデコードを使いやすくするために、デコード前のテキストはバイトシーケンス値であるべきだが、マルチバイトとユニバイトのバッファーいずれでも許すようになっている(マルチバイトバッファーの場合rawバイト値は8ビット文字で表現されていること)。通常、デコードされたテキストでバッファー内の元のテキストは置き換えられるが、オプション引数destinationはそれを変更する。destinationがバッファーなら、デコードされたテキストは、そのバッファーのポイントの後に挿入される(ポイントは移動しない)。これがtなら、このコマンドはデコードされたテキストを挿入せずに、それをマルチバイト文字列としてリターンする。

デコードされたテキストが何らかのバッファーに挿入された場合、このコマンドはデコードされたテキストの長さをリターンする。

このコマンドは、デコードされたテキストに、テキストプロパティcharsetをputする。このプロパティの値は、元ののテキストのデコードに使用された文字セットを示す。

Function: decode-coding-string string coding-system &optional nocopy buffer

この関数は、coding-systemでstring内のテキストをデコードする。これはデコードされたテキストを含む新たな文字列をリターンするが、nocopyが非nilの場合、些細なデコード処理ならstring自体をリターンするかもしれない。明示的なデコードを使いやすくするために、stringのコンテンツはバイトシーケンス値をもつユニバイト文字列であるべきだが、マルチバイト文字列も許すようになっている(マルチバイト形式で8ビットバイトを含むと仮定する)。

オプション引数bufferがバッファーを指定する場合、デコードされたテキストは、そのバッファー内のポイントの後に挿入される(ポイントは移動しない)。この場合、リターン値はデコードされたテキストの長さとなる。

この関数は、デコードされたテキストに、テキストプロパティcharsetをputする。このプロパティの値は、元のテキストのデコードに使用された、文字セットを示す。

(decode-coding-string "Gr\374ss Gott" 'latin-1)
     ⇒ #("Grüss Gott" 0 9 (charset iso-8859-1))

Function: decode-coding-inserted-region from to filename &optional visit beg end replace

この関数は、fromからtoのテキストを、あたかもファイルfilenameから、与えられた残りの引数でinsert-file-contentsを使用して読み込んだかのようにデコードする。

デコードせずにファイルからテキストを読み込んだ後、やはりデコードすることを決心したときに使用するのが、この関数の通常の使い方である。テキストを削除して再度読み込むかわりに、この関数を呼び出せばデコードして読み込むことができる。

33.10.8 端末I/Oのエンコーディング

Emacsは、キーボード入力のデコード、および端末出力のエンコードにコーディングシステムを使用できます。これはLatin-1のような、特定のエンコーディングを使用したテキストの送信や表示を行う端末にとって有用です。端末I/Oをエンコードまたはデコードする際、Emacsはlast-coding-system-usedをセットしません。

Function: keyboard-coding-system &optional terminal: この関数は、terminalからのキーボード入力をデコードするために使用する、コーディングシステムをリターンする。no-conversionという値は、何のデコーディングも行われていないことを意味する。terminalが省略またはnilなら、それは選択されたフレームの端末を意味する。複数の端末を参照のこと。

Command: set-keyboard-coding-system coding-system &optional terminal: このコマンドは、terminalからのキーボード入力のデコードに使用するコーディングシステムとして、coding-systemを指定する。coding-systemがnilなら、キーボード入力をデコードしないことを意味する。terminalがフレームなら、それはそのフレームの端末を意味する。nilなら、それはカレントで選択されたフレームの端末を意味する。複数の端末を参照のこと。

Function: terminal-coding-system &optional terminal: この関数は、terminalからの端末出力のエンコードに使用中のコーディングシステムをリターンする。no-conversionという値は、何のデコーディングも行われていないことを意味する。terminalがフレームなら、それはそのフレームの端末を意味する。nilなら、それはカレントで選択されたフレームの端末を意味する。

Command: set-terminal-coding-system coding-system &optional terminal: この関数は、terminalからの端末出力のエンコードに使用するためののコーディングシステムとして、coding-systemを指定する。coding-systemがnilなら、端末出力をエンコードしないことを意味する。terminalがフレームなら、それはそのフレームの端末を意味する。nilなら、それはカレントで選択されたフレームの端末を意味する。

33.11 入力メソッド

入力メソッド(input methods)とは、キーボードから非ASCII文字を簡単に入力する手段を提供します。プログラムが読み取ることを意図して非ASCII文字とエンコーディングを相互に変換するコーディングシステムとは異なり、入力メソッドはヒューマンフレンドリーなコマンドを提供します(テキストを入力するためにユーザーが入力メソッドを使う方法については、Input Methods in The GNU Emacs Manualを参照のこと)。0入力メソッドの定義方法はまだこのマニュアルにはありませんが、ここではそれらの使い方について説明します。

現在のところ、入力メソッドは文字列で名前をもっていますが、将来的には入力メソッド名として、シンボルも利用可能になるかもしれません。

Variable: current-input-method: この変数は、カレントバッファーで現在アクティブな、入力メソッドの名前を保持する(方法に依らずセット時には各バッファーで自動的にローカルになる)。バッファーで現在アクティブな入力メソッドがなければ、値はnil。

User Option: default-input-method: この変数は、入力メソッドを選択するコマンドにたいして、デフォルトの入力メソッドを保持する。current-input-methodと異なり、この変数は通常はグローバルである。

Command: set-input-method input-method: このコマンドは、カレントバッファーで入力メソッドinput-methodをアクティブにする。同様にdefault-input-methodにinput-methodのセットも行う。input-methodがnilなら、このコマンドはカレントバッファーで入力メソッドを非アクティブにする。

Function: read-input-method-name prompt &optional default inhibit-null

この関数は、プロンプトpromptとともに、ミニバッファーで入力メソッドの名前を読み取る。defaultが非nilの場合、ユーザーの入力が空なら、それがデフォルトとしてリターンされる。しかし、inhibit-nullが非nilなら、空の入力はエラーをシグナルする。

リターン値は文字列。

Variable: input-method-alist

この変数は、サポートされているすべての入力メソッドを定義する。各要素は1つの入力メソッドを定義し、以下の形式をもつ:

(input-method language-env activate-func
 title description args...)

ここでinput-methodはメソッド名の文字列、language-envはこの入力メソッドが推奨される言語環境の名前の文字列である(これはドキュメントとしての目的のみの役割を果たす)。

activate-funcは、このメソッドをアクティブにするために呼び出す関数、もしあればargsはactivate-funcに渡す引数である。つまり、activate-funcの引数は、input-methodとargsである。

titleは、ソン入力メソッドがアクティブな間、それをモードライン内に表示するための文字列、descriptionはそのメソッドを説明し、それが何に適するかを説明する文字列である。

入力メソッドのための基本的インターフェースは、変数input-method-functionです。単一イベントの読み取り、および入力メソッドの呼び出しを参照してください。

33.12 locale

In POSIX, locales control which language to use in language-related features. These Emacs variables control how Emacs interacts with these features.

Variable: locale-coding-system: This variable specifies the coding system to use for decoding system error messages and—on X Window system only—keyboard input, for sending batch output to the standard output and error streams, for encoding the format argument to format-time-string, and for decoding the return value of format-time-string.

Variable: system-messages-locale: この変数は、システムエラーメッセージを生成するために使用するlocaleを指定する。locale変更により、メッセージが異なる言語になったり、異なる表記になり得る。この変数がnilなら、通常のPOSIX方式のように、localeは環境変数により指定される。

Variable: system-time-locale: この変数は、タイムバリューをフォーマットするために使用するlocaleを指定する。locale変更により、異なる慣習によりメッセージが表示され得る。この変数がnilなら、通常のPOSIX方式のように、localeは環境変数により指定される。

Function: locale-info item

この変数は、もし利用可能なら、カレントPOSIX localeにたいするlocaleデータitemをリターンする。itemは以下のシンボルのいずれかであること:

codeset: 文字列として文字セットをリターンする(localeアイテムのCODESET)。
days: 曜日名からなる7要素のベクターをリターンする(localeアイテムのDAY_1からDAY_7)。
months: 月の名前からなる12要素のベクターをリターンする(localeアイテムのMON_1からMON_12)。
paper: (width height)というリストで、mm単位でデフォルト用紙サイズをリターンする(localeアイテムPAPER_WIDTHおよびPAPER_HEIGHT)。

システムが要求された情報を提供できない、またはitemが上記いずれのシンボルでもなければ、値はnilとなる。リターン値内のすべての文字列は、locale-coding-systemを使用してデコードされる。localeおよびlocaleアイテムについての詳細な情報は、Locales in The GNU Libc Manualを参照されたい。

34 検索とマッチング

GNU Emacsは、バッファーから指定されたテキストを検索するために、２つの手段を提供します。それは文字列の正確一致検索(exact string search)と、正規表現検索(regular expression search)です。正規表現検索の後、マッチしたテキストが正規表現壱阡にマッチしたのか、それとも正規表現のさまざまな部分に一致したかを判断するために、マッチデータ(match data)を調べることができます。

34.1 文字列の検索		正確なマッチの検索。
34.2 検索と大文字小文字		case-independentまたはcase-significantな検索。
34.3 正規表現		文字列クラスの記述。
34.4 正規表現の検索		regexpにたいするマッチの検索。
34.5 POSIX正規表現の検索		最長マッチにたいするPOSIXスタイルのマッチ。
34.6 マッチデータ		文字列またはregexp検索後に、テキストがマッチした部分を見つける。
34.7 検索と置換		検索と置換を繰り返すコマンド。
34.8 編集で使用される標準的な正規表現		センテンスやページ等を探すために有用なregexp。

‘skip-chars…’関連の関数も、ある種の検索を行います。文字のスキップを参照してください。文字プロパティ内の変更を検索するには、テキストプロパティの検索関数を参照してください。

34.1 文字列の検索

バッファー内のテキストを検索するための、プリミティブ関数が存在します。これらはプログラム内での使用を意図したものですが、インタラクティブに呼び出すこともできます。これらをインタラクティブに呼び出した場合は、検索文字列の入力を求め、引数limitおよびnoerrorはnil、repeatは1になります。インタラクティブ検索に関するより詳細な情報は、Searching and Replacement in The GNU Emacs Manualを参照してください。

以下の検索関数は、バッファーがマルチバイトバッファーならマルチバイト、ユニバイトバッファーならユニバイトに、検索文字列を変換します。テキストの表現方法を参照してください。

Command: search-forward string &optional limit noerror count

この関数は、stringにたいする正確なマッチを、ポイントから前方に検索する。成功したら、見つかったマッチの終端にポイントをセットして、ポイントの新たな値をリターンする。マッチが見つからない場合の値と副作用は、noerror(以下参照)に依存する。

以下の例では、ポイントは最初は行の先頭にある。その後の(search-forward "fox")により、ポイントは‘fox’の最後の文字の後に移動する:

---------- Buffer: foo ----------
∗The quick brown fox jumped over the lazy dog.
---------- Buffer: foo ----------

(search-forward "fox")
     ⇒ 20

---------- Buffer: foo ----------
The quick brown fox∗ jumped over the lazy dog.
---------- Buffer: foo ----------

引数limitは検索の境界を指定し、それはカレントバッファー内の位置であること。その位置を超えるようなマッチは、受け入れられない。limitが省略またはnilの場合のデフォルトは、そのバッファーのアクセス可能範囲の終端である。

検索失敗時に何が起こるかは、noerrorの値に依存する。noerrorがnilなら、search-failedはエラーをシグナルする。noerrorがtなら、search-forwardはnilをリターンして、何も行わない。noerrorがnilとtいずれでもなければ、search-forwardはポイントを境界上限に移動して、nilをリターンする。

引数noerrorは、マッチに失敗した有効な検索だけに影響する。無効な引数は、noerrorとは無関係にエラーとなる。

If count is a positive number n, the search is done n times; each successive search starts at the end of the previous match. If all these successive searches succeed, the function call succeeds, moving point and returning its new value. Otherwise the function call fails, with results depending on the value of noerror, as described above. If count is a negative number -n, the search is done n times in the opposite (backward) direction.

Command: search-backward string &optional limit noerror count: この関数は、ポイントから後方にstringを検索する。これはsearch-forwardと似ているが、前方ではなく後方に検索する点が異なる。後方への検索では、ポイントはマッチの先頭に残される。

Command: word-search-forward string &optional limit noerror count

This function searches forward from point for a word match for string. If it finds a match, it sets point to the end of the match found, and returns the new value of point.

単語マッチはstringを単語のシーケンスとみなし、それらを分ける句読点は無視する。これはバッファーから、同じ単語シーケンスを検索する。単語はそれぞれバッファー内で明確に区別されていなければならないが(単語‘ball’の検索は単語‘balls’にマッチしない)、句読点やスペース等の細部は無視される(‘ball boy’を検索すると‘ball. Boy!’にマッチする)。

以下の例では、ポイントは最初バッファー先頭にある。検索により、ポイントは‘y’と‘!’の間に残される。

---------- Buffer: foo ----------
∗He said "Please!  Find
the ball boy!"
---------- Buffer: foo ----------

(word-search-forward "Please find the ball, boy.")
     ⇒ 39

---------- Buffer: foo ----------
He said "Please!  Find
the ball boy∗!"
---------- Buffer: foo ----------

limitが非nilなら、それはカレントバッファー内の位置であること。これはその検索の境界上限を指定する。見つかったマッチは、その位置を超えてはならない。

noerrorがnilなら、word-search-forwardはエラーをシグナルする。noerrorがtなら、エラーをシグナルするかわりに、nilをリターンする。noerrorがnilとtいずれでもなければ、ポイントをlimit(またはバッファーのアクセス可能範囲の終端)に移動して、nilをリターンする。

If count is a positive number, it specifies how many successive occurrences to search for. Point is positioned at the end of the last match. If count is a negative number, the search is backward and point is positioned at the beginning of the last match.

内部的には、word-search-forwardと関連する関数は、stringから句読点を無視した正規表現に変換するために、関数word-search-regexpを使用する。

Command: word-search-forward-lax string &optional limit noerror count: このコマンドはword-search-forwardと同じだが、stringが空白で開始または終了していなければ、stringの先頭または終端が単語境界にマッチする必要がない点が異なる。たとえば‘ball boy’の検索は‘ball boyee’にはマッチするが、‘balls boy’にはマッチしない。

Command: word-search-backward string &optional limit noerror count: この関数は、ポイントから後方へstringにマッチする単語を検索する。この関数はword-search-forwardと同様だが、後方に検索して、通常はマッチの先頭にポイントを残す点が異なる。

Command: word-search-backward-lax string &optional limit noerror count: このコマンドはword-search-backwardと同じだが、文字列が空白で開始または終了していなければ、stringの先頭または終端が単語境界にマッチする必要がない点が異なる。

34.2 検索と大文字小文字

デフォルトのEmacs検索では、検索するテキストの大文字と小文字は無視されます。検索対象に‘FOO’を指定すると、‘Foo’や‘foo’もマッチとみなされます。これは正規表現にも適用されます。つまり‘[aB]’は‘a’、‘A’、‘b’、‘B’にもマッチするでしょう。

この機能が望ましくなければ、変数case-fold-searchをnilにセットしてください。その場合、すべての文字は大文字小文字の違いを含めて、正確にマッチしなければなりません。これはバッファーローカル変数です。この変数の変更は、カレントバッファーだけに影響を与えます(バッファーローカル変数の概要を参照)。かわりにデフォルト値を変更することもできます。Lispコードでは、letを使用してcase-fold-searchを望む値にバインドするほうが、より一般的でしょう。

ユーザーレベルのインクリメンタル検索機能では、大文字小文字の区別が異なることに注意してください。検索文字列に含まれるのが小文字だけなら検索は大文字小文字の違いを無視しますが、検索文字列に1つ以上の大文字が含まれれば検索は大文字小文字の違いを区別するようになります。しかしLispコード内で使用される検索関数では、これは何も行いません。Incremental Search in The GNU Emacs Manualを参照してください。

User Option: case-fold-search: このバッファーローカル変数は、検索が大文字小文字の違いを無視するべきかどうかを決定する。この変数がnilなら、検索は大文字小文字の違いを無視しない。それ以外(とデフォルト)では、大文字小文字のかも無視する。

User Option: case-replace

この変数は、高レベルの置換関数が大文字小文字の違いを保持するべきかどうかを決定する。この変数がnilなら、それは置換テキストをそのまま使用することを意味する。非nil値は、置換されるテキストに応じて、置換テキストの大文字小文字を変換することを意味する。

この変数は、それを関数replace-matchの引数として渡すことにより使用される。マッチしたテキストの置換を参照のこと。

34.3 正規表現

正規表現(regular expression)、略してregexpは、文字列の(もしかしたら無限の)セットを表すパターンのことです。regexpにたいするマッチの検索は、とても強力な処理です。このセクションではregexpの記述方法、それ以降のセクションではそれらを検索する方法を示します。

正規表現を対話的に開発するために、M-x re-builderコマンドを使用できます。このコマンドは、別のバッファーに即座に視覚的なフィードバックを表示することにより、正規表現を作成するための便利なインターフェースを提供します。regexp編集とともに、ターゲットとなるバッファーのすべてのマッチがハイライトされます。カッコで括られたregexpの部分式(sub-expression)は別のフェイスで表示され、非常に複雑なregexpを簡単に検証することが可能になります。

34.3.1 正規表現の構文

正規表現は、少数の文字が特別な構成要素で、残りは通常の文字であるような構文をもちます。通常の文字は、その文字自身だけにマッチする、シンプルな正規表現です。特別な文字は‘.’、‘*’、‘+’、‘?’、‘[’、‘^’、‘$’、および‘\’です。将来、新たなスペシャル文字が定義されることはないでしょう。文字候補で終わる場合、‘]’はスペシャル文字です。文字候補の間では、‘-’はスペシャル文字です。‘[:’と、対応する‘:]’は、文字候補内の文字クラスです。正規表現内に出現する他の文字は、‘\’が前置されていない限り、通常の文字です。

たとえば‘f’はスペシャル文字ではなく通常文字なので、‘f’は文字列‘f’にマッチし、他の文字にはマッチしない正規表現です(これは文字列‘fg’にはマッチしないが、その文字列の部分にマッチする)。同様に、‘o’は‘o’だけにマッチします。

任意の2つの正規表現aとbは、結合することができます。結合した結果は、文字列の先頭からある長さの文字列がaにマッチし、残りの文字列がbにマッチするような文字列にマッチする正規表現になります。

単純な例として、文字列‘fo’だけにマッチする正規表現の構成要素‘fo’を取得するために、正規表現‘f’と‘o’を結合できます。

34.3.1.1 正規表現内の特殊文字

以下は、正規表現内で特別な文字のリストです:

‘.’ (Period)

これは、改行を除く1文字にマッチする。結合を使用して、‘a.b’のような正規表現を作成できる。これは‘a’で始まり‘b’で終わる3文字の文字列にマッチする。

‘*’

これは、それ自身が構成要素ではない。これは前置された正規表現を可能な限り繰り返したものにマッチすることを意味する、後置演算子である。したがって、‘o*’は任意の個数の‘o’にマッチする(‘o’を含まない場合もマッチする)。

‘*’は常に前置された表現の、最小の表現に適用される。つまり‘fo*’は‘o’の繰り返しであり、‘fo’の繰り返しではない。これは‘f’、‘fo’、‘foo’、...にマッチする。

The matcher processes a ‘*’ construct by matching, immediately, as many repetitions as can be found. Then it continues with the rest of the pattern. If that fails, backtracking occurs, discarding some of the matches of the ‘*’-modified construct in the hope that this will make it possible to match the rest of the pattern. For example, in matching ‘ca*ar’ against the string ‘caaar’, the ‘a*’ first tries to match all three ‘a’s; but the rest of the pattern is ‘ar’ and there is only ‘r’ left to match, so this try fails. The next alternative is for ‘a*’ to match only two ‘a’s. With this choice, the rest of the regexp matches successfully.

警告: ネストされた繰り返し処理は、それらが曖昧なマッチとなるような場合は、無期限な長時間の実行となり得る。たとえば文字列‘xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz’にたいして正規表現‘$x+y*$*a’のマッチを試みると、それが最終的に失敗するまでに数時間を要し得る。Emacsはその試みのいずれも機能しないと結論する前に、‘x’のグループ家のそれぞれを試みなければならない。さらに悪いことに、‘$x*$*’は無数の方法でnull文字列にマッチ可能なので、これは無限ループを引き起こす。これらの問題を避けるには、ネストされた繰り返しがバックトラッキングでの組み合わせ爆発(combinatorial explosion)が発生しないことを確実にするために注意深くチェックすること。

‘+’

これは‘*’のような後置演算子だが、これは前置された表現に少なくとも1回マッチしなければならない点が異なる。たとえば‘ca+r’は文字列‘car’や‘caaaar’にマッチするが、文字列‘cr’にはマッチせず、その一方で‘ca*r’はこれら3つすべての文字列にマッチする。

‘?’

これは‘*’のような後置演算子だが、これは前置された表現に1回、またはマッチしないかのいずれかでなければならない点が異なる。申‘ca?r’は‘car’と‘cr’にマッチするが、他にはマッチしない。

‘*?’, ‘+?’, ‘??’

These are non-greedy variants of the operators ‘*’, ‘+’ and ‘?’. Where those operators match the largest possible substring (consistent with matching the entire containing expression), the non-greedy variants match the smallest possible substring (consistent with matching the entire containing expression).

たとえば正規表現‘c[ad]*a’が文字列‘cdaaada’に適用されると文字列全体にマッチするが、正規表現‘c[ad]*?a’を同じ文字列に適用すると‘cda’だけにマッチする(ここでマッチが許された表現全体にたいする‘[ad]*?’の可能な最短マッチは‘d’である)。

‘[ … ]’

これは‘[’で始まり‘]’で終端される文字候補(character alternative)である。もっとも単純なケースでは、この２つのカッコ(brackets)の間にある文字が、この文字候補がマッチ可能な文字である。

したがって‘[ad]’は1つの‘a’と1つの‘d’の両方にマッチし、‘[ad]*’は‘a’と‘d’だけから構成された任意の文字列(空文字列を含む)にマッチする。つまり‘c[ad]*r’は‘cr’、‘car’、‘cdr’、‘caddaar’等にマッチする。

開始文字と終了文字の間に‘-’を記述することにより、文字候補内に文字範囲を含めることができる。つまり‘[a-z]’は小文字のASCIIアルファベット文字にマッチする。範囲は‘[a-z$%.]’のように個別の文字と自由に組み合わせることができる。これは任意のASCII小文字アルファベットと‘$’、‘%’、またはピリオドとマッチする。

case-fold-searchが非nilなら、‘[a-z]’は大文字アルファベットにもマッチする。‘[a-z]’のような範囲は、そのlocaleの照合順に影響されず、常にASCII順のシーケンスを表すことに注意。

さらに通常のregexpスペシャル文字は文字候補内では特別ではないことにも注意されたい。文字候補内部では‘]’、‘-’、‘^’という完全に異なる文字セットが特別に扱われる。

文字候補内に‘]’を含めるには、それを最初の文字にしなければならない。たとえば‘[]a]’は、‘]’と‘a’にマッチする。‘-’を含めるには、文字候補の最初または最後の文字として‘-’を記述するか、範囲の後に置くこと。つまり‘[]-]’は‘]’と‘-’の両方にマッチする。(以下で説明するように、ここでは‘\’は特別ではないので、文字候補内に‘]’を含めるために‘\]’は使用できない)。

文字候補内に‘^’を含めるには、先頭以外のいずれかの場所に置くこと。

ある範囲がユニバイト文字cで始まり、マルチバイト文字c2でお話場合、その範囲は2つの部分に分割される。1つはユニバイト文字‘c..?\377’、もう1つはマルチバイト文字‘c1..c2’である。ここでc1はc2が属する文字セットの最初の文字である。

文字候補には、名前付き文字クラスも指定できる(文字クラスを参照)。これはPOSIXの機能である。たとえば‘[[:ascii:]]’は、任意のASCII文字にマッチする。文字クラスの使用は、そのクラス内すべての文字を記述するのと等しい。しかし異なる文字数千を含むクラスもあるので、後者は実際は実現可能ではない。

‘[^ … ]’

‘[^’は補完文字候補(complemented character alternative)を開始する。これは、指定された以外の任意の文字とマッチする。つまり‘[^a-z0-9A-Z]’はアルファベットと数日前以外の、すべての文字にマッチする。

‘^’は文字クラス内では、先頭に記述されない限り特別ではない。‘^’に続く文字は、あたかもそれが先頭にあるかのように扱われる(言い換えると‘-’や‘]’は、ここでは特別ではない)。

マッチしない文字の1つとして改行が記述されていなければ、補完文字候補は改行にマッチできる。これはgrepのようなプログラム内でのregexpの扱いとは、対照的である。

文字候補のように、名前付き文字クラスを指定できる。たとえば‘[^[:ascii:]]’は、任意の非ASCII文字にマッチする。文字クラスを参照のこと。

‘^’

バッファーのマッチング時、‘^’は空文字列、ただしマッチ対象のテキスト内にある行の先頭(またはバッファーのアクセス可能範囲の先頭)だけにマッチする。それ以外のマッチは、すべて失敗する。つまり‘^foo’は、行の先頭に出現する‘foo’にマッチする。

バッファーではなく文字列とマッチする際は、‘^’は文字列の先頭、または改行文字の後にマッチする。

歴史的な互換性という理由により、‘^’は正規表現の先頭、または‘\(’、‘\(?:’、‘\|’の後だけで使用できる。

‘$’

これは‘^’と似ているが、行の終端(またはバッファーのアクセス可能範囲の終端)だけにマッチする。つまり‘x+$’は、行末にある1つ以上の‘x’からなる文字列にマッチする。

バッファーではなく文字列とマッチする際は、‘$’は文字列の終端、または改行文字の前にマッチする。

歴史的な互換性という理由により、‘$’は正規表現の先頭、または‘\(’、‘\(?:’、‘\|’の前だけで使用できる。

‘\’

これは2つの機能をもつ。スペシャル文字(‘\’を含む)のクォートと、追加のスペシャル文字の導入である。

‘\’はスペシャル文字をクォートするので、‘\$’は‘$’、‘\[’は‘[’だけにマッチする正規表現といったようになる。

‘\’はLisp文字列(文字列型を参照)の入力構文(read syntax)内でも特別な意味をもち、‘\’でクォートしなければならないことに注意。たとえば文字‘\’にマッチする正規表現は‘\\’である。文字‘\\’を含むLisp文字列を記述するには、別の‘\\’で‘\\’をクォートすることをLisp構文は要求する。したがって‘\’にマッチする正規表現にたいする入力構文は、"\\\\"となる。

注意してください: 歴史的な互換性のために、スペシャル文字はそれらがもつ特別な意味が意味を成さないコンテキスト内にある場合は、通常の文字として扱われます。たとえば‘*foo’は、‘*’が作用可能な前置された表現がないので、通常の‘*’として扱われます。この挙動に依存するのは悪い習慣です。どこにそれが出現しようと、スペシャル文字はすべてクォートしてください。

文字候補内で‘\’は何ら特別ではないので、‘-’や‘]’の特別な意味を取り除くことは決してありません。特別な意味をもたないような場合でも、これらの文字をクォートするべきではありません。バックスラッシュ以外の任意の1文字にマッチする‘[^\]’(Lisp文字列構文では"[^\\]")内でのように、これらの文字が特別な意味をもつ箇所では、これらの文字にバックスラッシュを前置する正当性があるので、それほど何も明解にはしないでしょう。

実際には、正規表現内に出現する‘]’は文字候補に近接しており、それ故にほとんどがスペシャル文字です。しかしリテラルの‘[’および‘]’の複雑なパターンにたいして、マッチを試みることも時にはあるかもしれません。そのような状況では、文字候補を囲う角カッコがどれなのかを判断するために、regexpを最初から注意深く解析するのが必要なときもあるかもしれません。たとえば‘[^][]]’は、補完文字候補‘[^][]’(角カッコ以外の任意の1文字とマッチする)と、その後のリテラルの‘]’により構成されます。

厳密にはregexp先頭の‘[’は特別で、‘]’は特別ではないというのがルールです。これはクォートされていない最初の‘[’で終わり、その後は文字候補になります。(文字クラス開始を除き)‘[’はもはや特別ではありませんが、‘]’は直後にスペシャル文字‘[’があるか、その‘[’の後に‘^’がある場合を除き、特別です。これは文字クラス終了ではない次のスペシャル文字‘]’まで続きます。これは文字候補を終了させて、通常の正規表現の構文をリストアします。クォートされていない‘[’は再び特別となり、‘]’は特別ではなくなります。

34.3.1.2 文字クラス

以下は文字候補内で使用できるクラスと、その意味についてのテーブルです:

‘[:ascii:]’: これは任意のASCII文字(コード0 – 127)にマッチする。
‘[:alnum:]’: This matches any letter or digit. For multibyte characters, it matches characters whose Unicode ‘general-category’ property (see section 文字のプロパティ) indicates they are alphabetic or decimal number characters.
‘[:alpha:]’: This matches any letter. For multibyte characters, it matches characters whose Unicode ‘general-category’ property (see section 文字のプロパティ) indicates they are alphabetic characters.
‘[:blank:]’: This matches horizontal whitespace, as defined by Annex C of the Unicode Technical Standard #18. In particular, it matches spaces, tabs, and other characters whose Unicode ‘general-category’ property (see section 文字のプロパティ) indicates they are spacing separators.
‘[:cntrl:]’: これはASCII制御文字にマッチする。
‘[:digit:]’: これは‘0’から‘9’までにマッチする。つまり‘[-+[:digit:]]’は‘+’と‘-’同様、任意の数にマッチする。
‘[:graph:]’: This matches graphic characters—everything except whitespace, ASCII and non-ASCII control characters, surrogates, and codepoints unassigned by Unicode, as indicated by the Unicode ‘general-category’ property (see section 文字のプロパティ).
‘[:lower:]’: これはカレントの大文字小文字テーブル(caseテーブルを参照)で小文字と判断される文字すべてにマッチする。case-fold-searchが非nilなら、これは大文字にもマッチする。
‘[:multibyte:]’: これは任意のマルチバイト文字にマッチする(テキストの表現方法を参照)。
‘[:nonascii:]’: これは非ASCII文字にマッチする。
‘[:print:]’: This matches any printing character—either whitespace, or a graphic character matched by ‘[:graph:]’.
‘[:punct:]’: これは任意の句読点文字(punctuation character)にマッチする(現在のところマルチバイト文字にたいしては、単語構文以外のすべてにマッチする)。
‘[:space:]’: これは空白文字構文(構文クラスのテーブルを参照)をもつ任意の文字にマッチする。
‘[:unibyte:]’: これは任意のユニバイト文字(テキストの表現方法を参照)にマッチする。
‘[:upper:]’: これはカレントの大文字小文字テーブル(caseテーブルを参照)で大文字と判断される文字すべてにマッチする。case-fold-searchが非nilなら、これは小文字にもマッチする。
‘[:word:]’: これは単語構文(構文クラスのテーブルを参照)をもつ任意の文字にマッチする。
‘[:xdigit:]’: これは16進数の数字‘0’から‘9’、‘a’から‘f’と‘A’から‘F’にマッチする。

34.3.1.3 正規表現内のバッククラッシュ構造

ほとんどの場合、‘\’の後の任意の文字は、その文字だけにマッチします。しかし、例外もいくつかあります。‘\’で始まる特定のシーケンスには、特別な意味をもつものがあります。以下は特別な‘\’構成要素のテーブルです。

‘\|’

これは選択肢を指定する。2つの正規表現aとb、その間にある‘\|’により、aまたはbのいずれかにマッチする表現が形成される。

つまり‘foo\|bar’は、‘foo’か‘bar’のいずれかにマッチし、他の文字列にはマッチしない。

‘\|’は周囲の適用可能な最大の表現に適用される。‘\|’を取り囲む‘$ … $’でグループ化することにより、グループ化の効力を制限できる。

複数の‘\|’の処理するための、完全なバックトラッキング互換が必要なら、POSIX正規表現関数を使用すること(POSIX正規表現の検索を参照)。

‘\{m\}’

これは、前のパターンを正確にm回繰り返す、後置演算子である。つまり‘x\{5\}’は文字列‘xxxxx’にマッチし、それ以外にはマッチしない。‘c[ad]\{3\}r’は‘caaar’、‘cdddr’、‘cadar’等にマッチする。

‘\{m,n\}’

is a more general postfix operator that specifies repetition with a minimum of m repeats and a maximum of n repeats. If m is omitted, the minimum is 0; if n is omitted, there is no maximum. For both forms, m and n, if specified, may be no larger than 2**15 - 1 .

たとえば‘c[ad]\{1,2\}r’は文字列‘car’、‘cdr’、‘caar’、‘cadr’、‘cdar’、‘cddr’にマッチし、それ以外にはマッチしない。
‘\{0,1\}’または‘\{,1\}’は、‘?’と同じ。
‘\{0,\}’または‘\{,\}’は‘*’と同じ。
‘\{1,\}’は‘+’と同じ。

‘$ … $’

これは、以下の3つの目的を果たす役目をもつグループ化構成要素である:

他の操作のために、一連の‘\|’選択肢を囲う。つまり正規表現‘$foo\|bar$x’は、‘foox’か‘barx’のいずれかにマッチする。
後置演算子‘*’、‘+’、‘?’による複雑な表現を囲う。つまり‘ba$na$*’は‘ba’、‘bana’、‘banana’、‘bananana’、...等、任意の数(0以上の文字列‘na’にマッチする。
‘\digit’(以下参照)による将来の参照にたいして、マッチする部分文字列を記録する。

この最後の目的は、カッコによるグループ化というアイデアによるものではない。これは同じ構成要素‘$ … $’である2つ目の目的に割当てられた別の機能だが、実際のところ2つの意味は衝突しない。しかし稀に衝突が発生することがあり、それが内気(shy)なグループの導入をもたらした。

‘$?: … $’

これは内気なグループ(shy group)の構成要素である。内気なグループは通常のグループの最初の2つの役目(他の演算子のネスト制御)を果たすが、これは番号を取得せず‘\digit’でその値を後方参照できない。内気なグループは、通常の内気でないグループを変更することなく自動的に追加できるので、機械的に正規表現を構築するのに、特に適している。

内気なグループ化は、非キャプチャリング(non-capturing)、あるいは番号なしグループ(unnumbered groups)とも呼ばれる。

‘$?num: … $’

これは明示的番号付きグループ(explicitly numbered group)の構成要素である。通常のグループ化では、位置をもとに番号が暗黙で取得されるが、これが不便な場合もあるだろう。この構成要素により、特定のグループに番号を強制できる。番号の付与に特別な制限はなく、複数のグループに同じ番号を付与でき、その場合は最後の1つがマッチ(もっとも右のマッチ)が採用される。暗黙的に番号付けされたグループは常に、前のグループより大きい最小の整数となる番号を取得する。

‘\digit’

これはグループ構成要素(‘$ … $’)の、digit番目にマッチしたテキストと同じテキストにマッチする。

言い換えると、最後のグループの後に、マッチ処理はそのグループによりマッチされたテキストの開始と終了を記憶する。その正規表現の先の箇所で、‘\’とその後にdigitを使用すれば、それが何であれ同じテキストにマッチさせることができる。

検索またはマッチングを行う関数に渡される、正規表現全体の中で最初の9つのグループ化構成要素にマッチする文字列には、その正規表現内で開きカッコが出現する順に1から9までの番号が割り当てられる。したがって‘\1’から‘\9’までを使用して、対応するグループ化構成要素によりマッチされたテキストを参照できる。

たとえば‘$.*$\1’は、一方がもう一方と等しいような2つの文字列から構成される、改行を含まない任意の文字列にマッチする。‘$.*$’は前半分にマッチし、これは何でもよいが、それに続く‘\1’はそれと同じテキストに正確にマッチしなければならない。

構成要素‘$ … $’が2回以上マッチする場合(これはたとえば後に‘*’をしたがえるとき発生し得る)は、最後のマッチだけが記録される。

正規表現内の特定のグループ化構成要素がマッチしなかった場合、たとえばそれが使用されない選択肢内にあったり、回数が0回の繰り返しの内部にあるなら、それに対応する‘\digit’構成は何にもマッチしない。人工的な例を用いると、‘$foo\(b*$\|lose\)\2’は‘lose’にマッチできない。外側のグループ内の2つ目の選択肢がマッチするものの、‘\2’が未定義となり、何にたいしてもマッチできない。しかし‘foobb’にたいしては、1つ目の選択肢が‘foob’にマッチし、‘\2’が‘b’にマッチするので、マッチが可能になる。

‘\w’

これは任意の単語構成文字にマッチする。エディターの構文テーブルが、どの文字が単語構成文字かを決定する。構文テーブルを参照のこと。

‘\W’

これは任意の非単語構成文字にマッチする。

‘\scode’

これは、構文がcodeであるような任意の文字にマッチする。ここでcodeは、構文コードを表す文字である。‘w’は単語構成要素、‘-’は空白文字、‘(’は開きカッコ、等である。空白文字構文を表すには、‘-’かスペース文字のいずれかを使用する。構文コードと、それらを意味する文字のリストは、構文クラスのテーブルを参照されたい。

‘\Scode’

これは、構文がcodeでないような任意の文字にマッチする。

‘\cc’

これは、カテゴリーがcであるような任意の文字にマッチする。ここでcは、カテゴリーを表す文字である。つまり標準カテゴリーテーブルで、‘c’はChinese(中国語)、‘g’はGreek(ギリシャ語)の文字となる。M-x describe-categories RETで現在定義済みの全カテゴリーのリストを確認できる。define-category関数を使用すれば、標準カテゴリーに加えて、カテゴリーを独自に定義することもできる(カテゴリーを参照)。

‘\Cc’

これは、カテゴリーがcではない任意の文字にマッチする。

以下は、空文字列にマッチ(つまり文字を何も消費しない)しますが、マッチするかどうかはコンテキストに依存するような正規表現を構築します。これらすべてにたいして、そのバッファーのアクセス可能範囲の先頭と終端は、あたかもそのバッファーの実際の先頭と終端のように扱われます。

‘\`’

これは空文字列、ただしバッファー先頭、またはマッチ対象の文字列の先頭だけにマッチする。

‘\'’

これは空文字列、ただしバッファー終端、またはマッチ対象の文字列の終端だけにマッチする。

‘\=’

これは空文字列、ただしポイント位置だけにマッチする(この構成要素はマッチ対象が文字列なら定義されない)。

‘\b’

これは空文字列、ただし単語の先頭だけにマッチする。つまり‘\bfoo\b’は、個別の単語として出現する‘foo’だけにマッチする。‘\bballs?\b’は、個別の単語として‘ball’または‘balls’にマッチする。

‘\b’は、隣接するテキストが何であるかと無関係に、バッファー(か文字列)の先頭または終端にマッチする。

‘\B’

これは空文字列、単語の先頭や終端、またはバッファー(か文字列)の先頭や終端以外にマッチする。

‘\<’

これは空文字列、ただし単語の先頭だけにマッチする。‘\<’は、後に単語構成文字が続く場合のみ、バッファー(か文字列)の先頭にマッチする。

‘\>’

これは空文字列、ただし単語の終端だけにマッチする。‘\<’は、コンテンツが単語構成文字で終わる場合のみ、バッファー(か文字列)の終端にマッチする。

‘\_<’

これは空文字列、ただしシンボルの先頭だけにマッチする。シンボルとは1つ以上の単語かシンボル構成文字のシーケンスである。‘\_<’は、後にシンボル構成文字が続く場合のみ、バッファー(か文字列)の先頭にマッチする。

‘\_>’

これは空文字列、ただし単語の終端だけにマッチする。‘\_>’は、コンテンツがシンボル構成文字で終わる場合のみ、バッファー(か文字列)の終端にマッチする。

すべての文字列が、有効な正規表現な訳ではありません。たとえば終端の‘]’がない文字選択肢ないで終わる文字列は無効であり、単一の‘\’で終わる文字列も同様です。いずれかの検索関数にたいして無効な正規表現が渡されると、invalid-regexpエラーがシグナルされます。

34.3.2 正規表現の複雑な例

以下は、後続の空白文字とともにセンテンスの終わりを認識するために、以前のEmacsで使用されていた、複雑な正規表現の例です(現在のEmacsは、関数sentence-endにより構築される、同様だがより複雑なregexpを使用する。編集で使用される標準的な正規表現を参照されたい)。

以下ではまず、(スペースとタブ文字を区別するために)Lisp構文の文字列としてregexpを示し、それを評価した結果を示します。文字列定数の開始と終了は、ダブルクォーテーションです。‘\"’は文字列の一部としてのダブルクォーテーション、‘\\’は文字列の一部としてのバックスラッシュ、‘\t’はタブ、‘\n’は改行を意味します。

"[.?!][]\"')}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
     ⇒ "[.?!][]\"')}]*\\($\\| $\\|  \\|  \\)[
]*"

改行とタブは、それら自身として出力されます。

この正規表現は連続する4つのパートを含み、以下のように解読できます:

[.?!]: この正規表現の1つ目のパートはピリオド、疑問符、感嘆符の3つのうち、いずれか1つにマッチする文字選択肢である。マッチはこれら3つの文字のいずれかで開始されなければならない(これは旧正規表現と、Emacsが使用する新たなデフォルトregexpが異なる1つのポイントである。新たな値は、後続の空白文字なすでセンテンスを終端する、いくつかの非ASCII文字を許容する)。
[]\"')}]*: パターンの2つ目のパートは任意の0個以上の閉じカッコおよびクォーテーションマークで、後にピリオド、疑問符、感嘆符があるかもしれない。\"は、文字列内でのダブルクォーテーションマークにたいするLisp構文である。最後の‘*’は、直前の正規表現(この場合は文字選択肢)の0回以上の繰り返しを示す。
\$$\\| $\\|\t\\| \$: パターンの3つ目のパートは、センテンスの後の空白文字、すなわち行の終端(スペースがあっても可)、タブ、または2つのスペースにマッチする。2連バックスラッシュはカッコと垂直バーを正規表現構文としてマークする。すなわちカッコはグループを句切り、垂直バーは選択肢を区別する。ダラー記号は行の終端へのマッチに使用される。
[ \t\n]*: 最後に、パターンの最終パートはセンテンスを終端させるために必要とされる以上の、余分な空白文字にマッチする。

34.3.3 正規表現の関数

以下の関数は、正規表現を扱います。

Function: regexp-quote string

この関数は、stringだけに正確にマッチするような正規表現をリターンする。looking-at内でのこの正規表現の使用は、そのバッファー内の次の文字がstringのときだけ成功するだろう。検索関数でのこの正規表現の使用は、検索されるテキストがstringを含むなら成功するだろう。正規表現の検索を参照のこと。

これにより、その正規表現を求める関数呼び出し時に、正確な文字列マッチまたは検索を要求できる。

(regexp-quote "^The cat$")
     ⇒ "\\^The cat\\$"

正規表現として記述されたコンテキストにおいて、正確な文字列マッチを結合することが、regexp-quoteの1つの使い方である。たとえば以下は空白文で囲まれた、stringの値であるような文字列を検索する:

(re-search-forward
 (concat "\\s-" (regexp-quote string) "\\s-"))

Function: regexp-opt strings &optional paren

この関数は、リストstringsの文字列だけにマッチする、効果的な正規表現をリターンする。これはマッチングや検索を可能な限り高速にする必要があるとき、たとえばFont Lockモードで有用である¹⁷。

The optional argument paren can be any of the following:

a string: The resulting regexp is preceded by paren and followed by ‘\)’, e.g. use ‘"\\(?1:"’ to produce an explicitly numbered group.
words: The resulting regexp is surrounded by ‘\<$’ and ‘$\>’.
symbols: The resulting regexp is surrounded by ‘\_<$’ and ‘$\_>’ (this is often appropriate when matching programming-language keywords and the like).
non-nil: The resulting regexp is surrounded by ‘$’ and ‘$’.
nil: The resulting regexp is surrounded by ‘$?:’ and ‘$’, if it is necessary to ensure that a postfix operator appended to it will apply to the whole expression.

The resulting regexp of regexp-opt is equivalent to but usually more efficient than that of a simplified version:

(defun simplified-regexp-opt (strings &optional paren)
 (let ((parens
        (cond
         ((stringp paren)       (cons paren "\\)"))
         ((eq paren 'words)    '("\\<\\(" . "\\)\\>"))
         ((eq paren 'symbols) '("\\_<\\(" . "\\)\\_>"))
         ((null paren)          '("\\(?:" . "\\)"))
         (t                       '("\\(" . "\\)")))))
   (concat (car paren)
           (mapconcat 'regexp-quote strings "\\|")
           (cdr paren))))

Function: regexp-opt-depth regexp: この関数は、regexp内のグループ化された構成要素(カッコで囲まれた正規表現)の総数をリターンする。これには内気なグループは含まれない(正規表現内のバッククラッシュ構造を参照)。

Function: regexp-opt-charset chars

この関数は文字リストchars内の文字にマッチする正規表現をリターンする。

(regexp-opt-charset '(?a ?b ?c ?d ?e))
     ⇒ "[a-e]"

34.4 正規表現の検索

GNU Emacsでは、インクリメンタル、または非インクリメンタルの両方で、正規表現(正規表現の構文を参照)にたいする次マッチを検索できます。インクリメンタル検索コマンドについては、Regular Expression Search in The GNU Emacs Manualを参照してください。ここでは、プログラム内で有用な検索関数だけを説明します。重要な関数はre-search-forwardです。

これらの検索関数は、バッファーがマルチバイトならルチバイトに、ユニバイトならユニバイトに、正規表現を変換します。テキストの表現方法を参照してください。

Command: re-search-forward regexp &optional limit noerror count

この関数はカレントバッファー内で、正規表現regexpにマッチするテキスト文字列を、前方へ検索する。この関数はregexpにマッチしない任意の量のテキストをスキップして、見つかった最初のマッチの終端にポイントを残す。これはポイントの新たな値をリターンする。

If limit is non-nil, it must be a position in the current buffer. It specifies the upper bound to the search. No match extending after that position is accepted. If limit is omitted or nil, it defaults to the end of the accessible portion of the buffer.

What re-search-forward does when the search fails depends on the value of noerror:

nil: search-failedエラーをシグナルする。
t: 何もせずnilをリターンする。
その他: ポイントをlimit(またはバッファーのアクセス可能範囲の終端)に移動して、nilをリターンする。

引数noerrorは、マッチに失敗した有効な検索だけに影響する。無効な引数は、noerrorとは無関係にエラーとなる。

以下の例では、ポイントは最初は‘T’の前にある。この検索を評価することにより、その行の終端(‘hat’の‘t’と改行の間)にポイントは移動する。

---------- Buffer: foo ----------
I read "∗The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(re-search-forward "[a-z]+" nil t 5)
     ⇒ 27

---------- Buffer: foo ----------
I read "The cat in the hat∗
comes back" twice.
---------- Buffer: foo ----------

Command: re-search-backward regexp &optional limit noerror count

この関数はカレントバッファー内で、正規表現regexpにマッチするテキスト文字列を、後方へ検索して、見つかった最初のマッチの先頭にポイントを残す。

この関数はre-search-forwardと似ているが、単なるミラーイメージ(mirror-image: 鏡像)ではない。re-search-forwardは、先頭が開始ポイントと可能な限り近いマッチを探す。re-search-backwardが完全なミラーイメージなら、終端が可能な限り近いマッチを探すだろう。しかし実際は先頭が可能な限り近い(かつ開始ポイントの前で終わる)マッチを探す。これは、与えられた位置にたいする正規表現マッチングが常に正規表現の先頭から終端に機能し、指定された開始位置から開始されるのが理由である。

re-search-forwardの真のミラーイメージには、正規表現を終端から先頭へマッチする特別な機能が要求されるだろう。それを実装するこによる問題に価値はない。

Function: string-match regexp string &optional start

この関数はstring内で、正規表現regexpにたいする最初のマッチの開始位置のインデックスをリターンする。string内のそのインデックスから検索は開始される。

たとえば、

(string-match
 "quick" "The quick brown fox jumped quickly.")
     ⇒ 4

(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     ⇒ 27

文字列の最初の文字のインデックスは1、2文字目は2、...となる。

If this function finds a match, the index of the first character beyond the match is available as (match-end 0). See section マッチデータ.

(string-match
 "quick" "The quick brown fox jumped quickly." 8)
     ⇒ 27

(match-end 0)
     ⇒ 32

Function: string-match-p regexp string &optional start: この述語関数はstring-matchと同じことを行うが、マッチデータの変更を避ける。

Function: looking-at regexp

この関数は、カレントバッファー内のポイント直後のテキストが、正規表現regexpにマッチするかどうかを判断する。“直後”の正確な意味は、その検索が“固定”され、ポイントの後の最初の文字からマッチが開始する場合のみ成功するということである。成功なら結果はt、それ以外はnilとなる。

この関数はポイントを移動しないが、マッチデータは更新する。マッチデータを参照のこと。マッチデータを変更することなくテストする必要があるなら、以下で説明するlooking-at-pを使用すること。

以下の例では、ポイントは‘T’の直前にある。それ以外の場所にある場合、結果はnilとなるだろう。

---------- Buffer: foo ----------
I read "∗The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(looking-at "The cat in the hat$")
     ⇒ t

Function: looking-back regexp limit &optional greedy

この関数は、ポイントの直前(ポイントで終わる)テキストがregexpとマッチしたらt、それ以外はnilをリターンする。

Because regular expression matching works only going forward, this is implemented by searching backwards from point for a match that ends at point. That can be quite slow if it has to search a long distance. You can bound the time required by specifying a non-nil value for limit, which says not to search before limit. In this case, the match that is found must begin at or after limit. Here’s an example:

---------- Buffer: foo ----------
I read "∗The cat in the hat
comes back" twice.
---------- Buffer: foo ----------

(looking-back "read \"" 3)
     ⇒ t
(looking-back "read \"" 4)
     ⇒ nil

If greedy is non-nil, this function extends the match backwards as far as possible, stopping when a single additional previous character cannot be part of a match for regexp. When the match is extended, its starting position is allowed to occur before limit.

一般的にlooking-backは低速なので、可能な限り使用は避けることを推奨する。この理由により、looking-back-pの追加は計画されていない。

Function: looking-at-p regexp: この述語関数はlooking-atと同様に機能するが、マッチデータを更新しない。

Variable: search-spaces-regexp

この変数が非nilなら、それは空白文字を検索する方法を告げる正規表現であること。この場合、検索される正規表現内のすべてのスペース属は、この正規表現を使用することを意味する。しかし‘[…]’、‘*’‘+’、‘?’のような構成要素内のスペースは、search-spaces-regexpの影響を受けない。

この変数はすべての正規表現検索、およびマッチ構成要素に影響するので、コードの可能な限り狭い範囲にたいして、一時的にバインドするべきである。

34.5 POSIX正規表現の検索

通常の正規表現関数は、‘\|’や繰り返しの構成要素を処理するために必要なときだけバックトラッキングを行いますが、何らかのマッチが見つかるまでの間だけ、これを継続します。そして成功した後に、見つかった最初のマッチを報告します。

このセクションでは、正規表現にたいしてPOSIX標準で指定された完全なバックトラッキングを処理する、他の検索関数を説明します。これらはPOSIXが要求する最長マッチを報告できるように、すべての可能なマッチを試み、すべてのマッチが見つかるまでバックトラッキングを継続します。これは非常に低速なので、本当に最長マッチが必要なときだけ、これらの関数を使用してください。

POSIXの検索およびマッチ関数は、非欲張りな繰り返し演算子(non-greedyを参照)を正しくサポートしません。これはPOSIXのバックトラッキングが、非欲張りな繰り返しのセマンチックと競合するからです。

Command: posix-search-forward regexp &optional limit noerror count: これはre-search-forwardと似ているが、正規表現マッチングにたいしてPOSIX標準が指定する、完全なバックトラッキングを行う点が異なる。

Command: posix-search-backward regexp &optional limit noerror count: これはre-search-backwardと似ているが、正規表現マッチングにたいしてPOSIX標準が指定する、完全なバックトラッキングを行う点が異なる。

Function: posix-looking-at regexp: これはlooking-atと似ているが、正規表現マッチングにたいしてPOSIX標準が指定する、完全なバックトラッキングを行う。

Function: posix-string-match regexp string &optional start: これはstring-matchと似ているが、正規表現にたいしてPOSIX標準が指定する、完全なバックトラッキングを行う。

34.6 マッチデータ

Emacsは、検索の間に見つかったテキスト片の開始と終了の位置を追跡しています。これはマッチデータ(match data)と呼ばれます。このマッチデータのおかげで、メールメッセージ内のデータのような複雑なパターンを検索した後、そのパターンの制御下でマッチ部分を抽出できるのです。

マッチデータには通常、もっとも最近の検索だけが記述されるので、後で参照したい検索と、そのマッチデータの使用の間に、誤って別の検索を行わないように、注意しなければなりません。誤って別の検索を避けるのが不可能な場合は、マッチデータの上書きを防ぐために、その前後でマッチデータの保存とリストアを行わなければなりません。

上書きを行わないと明記されていない限り、すべての関数は上書きを許されていることに注意してください。結果としてバックグラウンド(遅延実行のためのタイマーおよびアイドルタイマーを参照されたい)で暗黙に実行される関数は、おそらく明示的にマッチデータの保存とリストアを行うべきでしょう。

34.6.1 マッチしたテキストの置換

以下の関数は、最後の検索でマッチされたテキストのすべて、または一部を置換します。これはマッチデータにより機能します。

Function: replace-match replacement &optional fixedcase literal string subexp

この関数はバッファー、または文字列にたいして置換処理を行う。

あるバッファーで最後の検索を行った場合は、string引数を省略またはnilを指定するべきである。また最後に検索を行ったバッファーがカレントバッファーであることを確認すること。その場合、この関数はマッチしたテキストをreplacementで置換することにより、そのバッファーを編集する。これは、置換したテキスト終端にポイントを残す。

文字列にたいして最後の検索を行った場合は、同じ文字列がstringに渡される。その場合、この関数はマッチしたテキストがreplacementに置き換えられた、新たなテキストをリターンする。

fixedcaseが非nilなら、replace-matchは大文字小文字を変更せずに置換テキストを使用し、それ以外は置換されるテキストのcapitalize(先頭が大文字)されているかどうかに応じて、置換テキストを変換する。元のテキストがすべて大文字なら、置換テキストを大文字に変換する。元のテキストの単語すべてがcapitalizeされていたら、置換テキストのすべての単語をcapitalizeする。すべての単語が1文字かつ大文字なら、それらはすべて大文字の単語ではなく、capitalizeされた単語として扱われる。

literalが非nilなら、replacementはそのまま挿入されるが、必要に応じて大文字小文字の変更だけが行われる。これがnil(デフォルト)なら、文字‘\’は特別に扱われる。replacement内に‘\’が出現した場合、それは以下のシーケンスのいずれかの一部でなければならない:

‘\&’: これは置換されるテキスト全体を意味する。
‘\n’ （nは数字): これは、元のregexpのn番目の部分式にマッチするテキストを意味する。この部分式とは‘$…$’の内部にグループかされた式である。n番目のマッチがなければ、空文字列が代用される。
‘\\’: これは置換テキスト内で、単一の‘\’を意味する。
‘\?’: これは自身を意味する(replace-regexpと関連するコマンドの互換用。Regexp Replace in The GNU Emacs Manualを参照されたい)。

これら以外の‘\’に続く文字は、エラーをシグナルする。

‘\&’および‘\n’により行われる代替えは、もしあれば大文字小文字変換の後に発生する。したがって、代替えする文字列は決して大文字小文字変換されない。

subexpが非nilなら、それは全体のマッチではなく、マッチされたregexpの部分式番号subexpだけを置換することを指定する。たとえば‘foo $ba*r$’のマッチング後にreplace-matchを呼び出すと、subexpが1なら‘$ba*r$’にマッチしたテキストだけを置換することを意味する。

Function: match-substitute-replacement replacement &optional fixedcase literal string subexp: この関数は、replace-matchによりバッファーに挿入されるであろうテキストをリターンするが、バッファーを変更しない。これは‘\n’や‘\&’のような構成要素を、マッチしたグループで置き換えた実際の結果を、ユーザーに示したいとき有用である。引数replacement、およびオプションのfixedcase、literal、string、subexpは、replace-matchのときと同じ意味をもつ。

34.6.2 単純なマッチデータへのアクセス

このセクションでは、最後の検索またはマッチング操作で、それが成功した場合に何がマッチされたのかを調べるための、マッチデータ使用の方法を説明します。

マッチしたテキスト全体、または正規表現の特定のカッコで括られた部分式にたいして、問い合わせることができます。以下の関数でcountは、どの部分式かを指定できます。countが0ならマッチ全体を、countが正なら望む部分式を指定します。

正規表現での部分式とは、エスケープされたカッコ‘$…$’でグループ化された表現であることを思い出してください。count番目の部分式は、正規表現全体の先頭から‘\(’を数えることにより見つけられます。最初の部分式が1、2つ目が2、...となります。正規表現だけが部分式をもつことができ、単純な文字列検索の後で利用できるのはマッチ全体の情報だけです。

成功した検索すべては、マッチデータをセットします。したがって検索後は、別の検索を行うかもしれない関数を呼び出す前に、直後にマッチデータを問い合わせるべきです。別の検索を呼び出すかもしれない関数の前後で、かわりにマッチデータの保存とリストアすることもできます(マッチデータの保存とリストアを参照)。またはstring-match-pのような、マッチデータを変更しないと明示されている関数を使用してください。

検索が成功しようと失敗しようと、マッチデータは変更されます。現在はこのように実装されていますが、これは将来変更されるかもしれません。失敗した後のマッチデータを、信用しないでください。

Function: match-string count &optional in-string

この関数は、最後の検索またはマッチ処理でマッチしたテキストを、文字列としてリターンする。これはcountが0ならテキスト全体、countが正ならcount番目のカッコで括られた部分式に対応する部分だけをリターンする。

そのような最後の処理が、文字列にたいするstring-match呼び出しの場合は、引数in-stringに同じ文字列を渡すべきである。バッファーの検索またはマッチ後は、in-stringを省略するかnilを渡すべきである。しかし、最後に検索またはマッチを行ったバッファーが、match-string呼び出し時にカレントバッファーであることを確認すること。このアドバイスにしたがわない場合は、誤った結果となるだろう。

countが範囲外か、‘\|’選択肢内部の部分式が使用されない、または0回の繰り返しなら、値はnilとなる。

Function: match-string-no-properties count &optional in-string: この関数はmatch-stringと似ているが、結果がテキストプロパティをもたない点が異なる。

Function: match-beginning count

If the last regular expression search found a match, this function returns the position of the start of the matching text or of a subexpression of it.

countが0なら、値はマッチ全体の開始位置となる。それ以外なら、countは正規表現内の部分式を指定し、この関数の値はその部分式にたいするマッチの開始位置である。

使用されない、あるいは0回の繰り返しであるような‘\|’選択肢内部の部分式にたいして、値はnilになる。

Function: match-end count: この関数はmatch-beginningと似ているが、マッチの開始ではなく終了位置である点が異なる。

以下はマッチデータを使用する例です。コメントの数字はテキスト内での位置を示しています:

(string-match "\\(qu\\)\\(ick\\)"
              "The quick fox jumped quickly.")
              ;0123456789
     ⇒ 4

(match-string 0 "The quick fox jumped quickly.")
     ⇒ "quick"
(match-string 1 "The quick fox jumped quickly.")
     ⇒ "qu"
(match-string 2 "The quick fox jumped quickly.")
     ⇒ "ick"

(match-beginning 1)       ; ‘qu’にたいするマッチ先頭の
     ⇒ 4                 ;   インデックスは4

(match-beginning 2)       ; ‘ick’にたいするマッチ先頭の
     ⇒ 6                 ;   インデックスは6

(match-end 1)             ; ‘qu’にたいするマッチ終端の
     ⇒ 6                 ;   インデックスは6

(match-end 2)             ; ‘ick’にたいするマッチ終端の
     ⇒ 9                 ;   インデックスは9

別の例を以下に示します。ポイントは最初、行の先頭にあります。検索により、ポイントはスペースと単語‘in’の間にあります。マッチ全体の先頭はバッファーの9つ目の文字(‘T’)、1つ目の部分式にたいするマッチの先頭は13番目の文字(‘c’)です。

(list
  (re-search-forward "The \\(cat \\)")
  (match-beginning 0)
  (match-beginning 1))
    ⇒ (17 9 13)

---------- Buffer: foo ----------
I read "The cat ∗in the hat comes back" twice.
        ^   ^
        9  13
---------- Buffer: foo ----------

(この場合、リターンされるインデックスはバッファー位置で、バッファーの1つ目の文字を1と数える。)

34.6.3 マッチデータ全体へのアクセス

関数match-dataおよびset-match-dataは、マッチデータ全体を一度に読み取り、または書き込みます。

Function: match-data &optional integers reuse reseat

この関数は、最後の検索によりマッチしたテキストのすべての情報を記録する、位置(マーカーか整数)をリターンする。要素0は、正規表現全体にたいするマッチの、先頭の位置である。要素1は、その正規表現にたいするマッチの、終端の位置である。次の2つの要素は、1つ目の部分式にたいするマッチの先頭と終了、...となる。一般的に要素番号 2n は(match-beginning n)に対応し、要素番号 2n + 1 は(match-end n)に対応する。

すべての要素は通常はマーカーかnilだが、もしintegersが非nilなら、それはマーカーのかわりに整数を使用することを意味する(この場合、マッチデータの完全なリストアwpey容易にするために、リストの最後の要素として、そのバッファー自身が追加される)。string-matchにより、最後の検索が文字列にたいして行われた場合、マーカーは文字列無いをポイントできないので、常に整数が使用される。

reuseが非nilなら、それはリストであること。この場合、match-dataはマッチデータをreuse内に格納する。つまりreuseは、破壊的に変更される。reuseが、正しい長さである必要はない。特定のマッチデータにたいして長さが十分でなければ、リストは拡張される。reuseが長過ぎる場合、長さはそのままで使用しない要素にはnilがセットされる。この機能には、ガベージコレクションの必要頻度を減らす目的がある。

reseatが非nilなら、reuseリスト内のすべてのマーカーは、存在しない場所を指すよう再設定される。

他の場合と同様、検索関数とその検索のマッチデータへのアクセスを意図するmatch-data呼び出しの間に介入するような検索があってはならない。

(match-data)
     ⇒  (#<marker at 9 in foo>
          #<marker at 17 in foo>
          #<marker at 13 in foo>
          #<marker at 17 in foo>)

Function: set-match-data match-list &optional reseat

この関数は、match-listの要素からマッチデータをセットする。match-listは、前のmatch-data呼び出しの値であるようなリストであること(正確には同じフォーマットなら他のものでも機能するだろう)。

match-listが存在しないバッファーを参照する場合でも、エラーとはならない。これは無意味だが害のない方法で、マッチデータをセットする。

reseatが非nilなら、リストmatch-list内のすべてのマーカーは、存在しない場所を指すよう再設定される。

store-match-dataは、半ば時代遅れなset-match-dataのエイリアスである。

34.6.4 マッチデータの保存とリストア

以前に行った検索にたいするマッチデータを後で使用するために保護する必要があるなら、検索を行うかもしれない関数の呼び出し時に、その呼び出し前後でマッチデータの保存とリストアを行う必要があるでしょう。以下はマッチデータ保存に失敗した場合に発生する問題を示す例です:

(re-search-forward "The \\(cat \\)")
     ⇒ 48
(foo)                   ; fooが他の検索を行うと
(match-end 0)
     ⇒ 61              ; 結果は期待する48と異なる!

save-match-dataで、マッチデータの保存とリストアができます:

Macro: save-match-data body…: このマクロはbodyを実行して、その前後のマッチデータの保存とリストアをする。リターン値は、body内の最後のフォームの値。

set-match-dataとmatch-dataを一緒に使用して、save-match-dataの効果を真似ることができます。以下は、その方法です:

(let ((data (match-data)))
  (unwind-protect
      …   ; 元のマッチデータを変更してもOK
    (set-match-data data)))

プロセスフィルター関数(see section プロセスのフィルター関数)、およびプロセスセンチネル(see section センチネル: プロセス状態の変更の検知)実行時は、Emacsが自動的にマッチデータの保存とリストアを行います。

34.7 検索と置換

バッファーのある部分で、regexpにたいするすべてのマッチを見つけてそれらを置換したい場合は、以下のようにre-search-forwardとreplace-matchを使用して、明示的なループを記述するのが最良の方法です:

(while (re-search-forward "foo[ \t]+bar" nil t)
  (replace-match "foobar"))

replace-matchの説明は、Replacing the Text that Matchedを参照してください。

しかし文字列内のマッチの置換、特にそれを効果的に行いたい場合は、より複雑になります。そのため、Emacsはこれを行うための関数を提供します。

Function: replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start

この関数はstringをコピーしてregexpにたいするマッチを検索し、それらをrepに置き換える。これは変更されたコピーwリターンする。startが非nilなら、マッチにたいする検索はstring内のそのインデックスから開始され、そのインデックスより前で始まるマッチは変更されない。

この関数は置換を行うためにreplace-matchを使用し、オプション引数fixedcase、literal、subexpをreplace-matchに渡す。

文字列のかわりに、repは関数でもよい。この場合、replace-regexp-in-stringはそれぞれのマッチにたいして、そのテキストを単一の引数としてrepを呼び出す。これはrepがリターンする値を収集して、それを置換文字列としてreplace-matchに渡す。この時点でのマッチデータはstringの部分文字列にたいするregexpのマッチ結果である。

query-replaceの行に関するコマンドを記述したい場合は、perform-replaceを使用してこれを行うことができる。

Function: perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end backward region-noncontiguous-p

This function is the guts of query-replace and related commands. It searches for occurrences of from-string in the text between positions start and end and replaces some or all of them. If start is nil (or omitted), point is used instead, and the end of the buffer’s accessible portion is used for end. (If the optional argument backward is non-nil, the search starts at end and goes backward.)

query-flagがnilなら、マッチすべてを置換する。それ以外の場合は、それぞれにたいしてユーザーにたいして何をすべきか問い合わせる。

regexp-flagが非nilならfrom-stringは正規表現とみなされ、それ以外はリテラルとしてマッチしなければならない。delimited-flagが非nilなら、単語境界に囲まれた置換だけが考慮される。

引数replacementsは、マッチを何で置き換えるかを指定する。文字列ならその文字列を使用する。サイクル順に使用される文字列リストでもよい。

replacementsがコンスセル(function . data)なら、これは置換テキストを取得するためにそれぞれのマッチ後にfunctionを呼び出すことを意味する。この関数はdataと、すでに置換された個数という、2つの引数で呼び出される。

repeat-countが非nilなら、それは整数であること。その場合、サイクルを次に進める前に、replacementsリスト内の各文字列を何度使用するかを指定する。

from-stringが大文字アルファベットを含む場合、perform-replaceはcase-fold-searchをnilにバインドして、大文字小文字を変換せずにreplacementsを使用する。

キーマップquery-replace-mapは通常、問い合わせにたいして可能なユーザー応答を定義する。引数mapが非nilなら、それはquery-replace-mapのかわりに使用するキーマップを指定する。

Non-nil region-noncontiguous-p means that the region between start and end is composed of noncontiguous pieces. The most common example of this is a rectangular region, where the pieces are separated by newline characters.

この関数はfrom-stringの次のマッチを検索するために、2つの関数のうち1つを使用する。これらの関数は2つの変数replace-re-search-functionとreplace-search-functionにより指定される。引数regexp-flagが非nilなら前者、nilなら後者が呼び出される。

Variable: query-replace-map

この変数はperform-replaceにたいする有効なユーザー応答を定義するスペシャルキーマップを保持し、コマンドはy-or-n-pやmap-y-or-n-pと同様に、それを使用する。このマップは2つの点において普通のマップと異なる。

The key bindings are not commands, just symbols that are meaningful to the functions that use this map.
プレフィクスキーはサポートされない。各キーバインディングは単一イベントキーシーケンスでなければならない。これは入力を取得するために、関数がread-key-sequenceを使用せず、かわりに単一イベントを読み取って、それを“手動”で照合する。

Here are the meaningful bindings for query-replace-map. Several of them are meaningful only for query-replace and friends.

act: 判断している対象にたいしてアクションを起こす(言い換えると“yes”)。
skip: この問いにたいしてアクションを起こさない(言い換えると“no”)。
exit: この問いにたいして“no”を答えて、一連の問いすべてにたいして“no”が応答されたとみなし、問い合わせをあきらめる。
exit-prefix: exitと似ているが、unread-command-eventsにたいして押下されたキーを追加する(その他のイベント入力の機能を参照)。
act-and-exit: この問いにたいして“yes”を答えて、一連の問いすべてにたいして後続の問いに“no”が応答されるとみなし、問い合わせをあきらめる。
act-and-show: この問いに“yes”を答えるが結果を表示して、まだ次の問いへ進まない。
automatic: これ以上のユーザーとの対話を行わず、この問いと後続の問いにたいして“yes”を答える。
backup: 前に問い合わせた以前の場所に戻る。
undo: Undo last replacement and move back to the place where that replacement was performed.
undo-all: Undo all replacements and move back to the place where the first replacement was performed.
edit: この問いに対処するために、通常とられるアクションのかわりに再帰編集にエンターする。
edit-replacement: ミニバッファー内で、この問いにたいする置換を編集する。
delete-and-edit: 検討中のテキストを削除して、それを置換するために再帰編集にエンターする。
recenter
scroll-up
scroll-down
scroll-other-window
scroll-other-window-down: 指定されたウィンドウスクロール操作を行い、同じ問いを再度尋ねる。この問いにはy-or-n-pと、関連する関数だけが使用される。
quit: 即座にquitを行う。この問いにはy-or-n-pと、関連する関数だけが使用される。
help: ヘルプを表示して、再度尋ねる。

Variable: multi-query-replace-map

This variable holds a keymap that extends query-replace-map by providing additional keybindings that are useful in multi-buffer replacements. The additional bindings are:

automatic-all: 残りすべてのバッファーにたいして、それ以上の対話をせず、その問いと後続のすべての問いに“yes”を答える。
exit-current: この問いに“no”を答えて、カレントバッファーにたいする一連の問いすべてをあきらめる。そしてシーケンス内の次のバッファーへ問いを継続する。

Variable: replace-search-function: この変数は、置換する次の文字列を検索するためにperform-replaceが呼び出す関数を指定する。デフォルト値はsearch-forward。それ以外の値の場合は、search-forwardの最初の3つの引数を引数とする関数を指定すること(文字列の検索を参照)。

Variable: replace-re-search-function: この変数は、置換する次のregexpを検索するためにperform-replaceが呼び出す関数を指定する。デフォルト値はre-search-forward。それ以外の値の場合は、re-search-forwardの最初の3つの引数を引数とする関数を指定すること(正規表現の検索を参照)。

34.8 編集で使用される標準的な正規表現

このセクションでは、編集において特定の目的のために使用される正規表現を保持する変数をいくつか説明します。

User Option: page-delimiter: これはページを分割する行開始を記述する、正規表現である。デフォルト値は"^\014"("^^L"または"^\C-l"のこと)。これはフォームフィード文字(改頁文字)で始まる行とマッチする。

以下の2つの正規表現を、常に行頭からマッチが始まる正規表現とみなすべきではありません。これらを‘^’にマッチするアンカーとして使用するべきではありません。ほとんどの場合、パラグラフコマンドは行頭にたいしてのみマッチのチェックを行い、これは‘^’が不要であることを意味します。非0の左マージンが存在する場合、これらは左マージンの後から始まるマッチに適用されます。その場合、‘^’は不適切でしょう。しかし左マージンを決して使用しないモードでは、‘^’は無害でしょう。

User Option: paragraph-separate: これは、パラグラフを分割する行の開始を認識する正規表現である(これを変更する場合はparagraph-startも変更する必要があるかもしれない)。デフォルト値は"[ \t\f]*$"で、これは(左マージン以降)すべてがスペース、タブ、フォームフィードで構成される行とマッチする。

User Option: paragraph-start: これは、パラグラフを開始または分割する行の開始を認識する正規表現である。デフォルト値は"\f\\|[ \t]*$"で、これは(左マージン以降)すべてが空白文字で構成される行、またはフォームフィードで始まる行とマッチする。

User Option: sentence-end

非nilなら、以降に続く空白文字を含めてセンテンスの終わりを記述する正規表現であること(これとは無関係にパラグラフ境界もセンテンスを終了させる)。

値がnil(デフォルト)なら、関数sentence-endがregexpを構築する。センテンス終端の認識に使用するregexpを得るのに、常に関数sentence-endを使用するべきなのは、これが理由である。

Function: sentence-end: この関数は、変数sentence-endが非nilなら、その値をリターンする。それ以外なら、変数sentence-end-double-space(Definition of sentence-end-double-spaceを参照)、sentence-end-without-period、sentence-end-without-spaceにもとづくデフォルト値をリターンする。

35 構文テーブル

構文テーブル(syntax table)は、バッファー内のそれぞれの文字にたいして、構文的な役割を指定します。単語、シンボル、その他の構文要素の開始と終了の判定に、これを使用できます。この情報はFont Lockモード(Font Lockモードを参照)や、種々の複雑な移動コマンド(モーションを参照)を含む、多くのEmacs機能により使用されます。

35.1 構文テーブルの概念		構文テーブルの基本的概念。
35.2 構文記述子		文字がクラス分けされる方法。
35.3 構文テーブルの関数		構文テーブルを作成、調査、変更する方法。
35.4 構文プロパティ		テキストプロパティによる構文テーブルのオーバーライド。
35.5 モーションと構文		特定の構文による文字間の移動。
35.6 式のパース		構文テーブル使用によるバランスのとれた式の解析。
35.7 構文テーブルの内部		構文テーブルの情報が格納される方法。
35.8 カテゴリー		文字構文をクラス分けする別の手段。

35.1 構文テーブルの概念

構文テーブルとは、それぞれの文字の構文クラス(syntax class)や、その他の構文的プロパティを照合するために使用できる、データ構造のことです。構文テーブルは、テキストを横断したスキャンや移動のために、Lispプログラムにより使用されます。

構文テーブルは、内部的には文字テーブルです(文字テーブルを参照)。インデックスcの要素はコードcの文字を記述します。値は該当する文字の構文を指定するコンスセルです。詳細はSee section 構文テーブルの内部を参照してください。しかし構文テーブルの内容を変更または調べるためにasetやarefを使用するかわりに、通常は高レベルな関数char-syntaxやmodify-syntax-entryを使用するべきです。これらについては構文テーブルの関数で説明します。

Function: syntax-table-p object: この関数はobjectが構文テーブルなら、tをリターンする。

バッファーはそれぞれ自身のメジャーモードをもち、それぞれのメジャーモードはさまざまな文字の構文クラスにたいして独自のアイデアをもっています。たとえばLisモードでは文字‘;’はコメントの開始ですが、Cモードでは命令文の終端になります。これらのバリエーションをサポートするために、構文テーブルはそれぞれのバッファーにたいしてローカルです。一般的に各メジャーモードは自身の構文テーブルをもち、そのモードを使用するすべてのバッファーにそれがインストールされます。たとえば変数emacs-lisp-mode-syntax-tableはEmacsのLispモードが使用する構文テーブル、c-mode-syntax-tableはCモードが使用する構文テーブルを保持します。あるメジャーモードの構文テーブルを変更すると、そのモードのバッファー、およびその後でそのモードに置かれるすべてのバッファーの構文も同様に変更されます。複数の類似するモードが1つの構文テーブルを共有することが、ときおりあります。構文テーブルをセットアップする方法の例は、メジャーモードの例を参照してください。

別の構文テーブルから構文テールを継承(inherit)できます。これを親構文テーブル(parent syntax table)と呼びます。構文テーブルは、ある文字にたいして構文クラス“inherit”を与えることにより、構文クラスを未指定にしておくことができます。そのような文字は、親構文テーブルが指定する構文クラスを取得します(構文クラスのテーブルを参照)。Emacsは標準構文テーブル(standard syntax table)を定義します。これはデフォルトとなる親構文テーブルであり、Fundamentalモードが使用する構文テーブルでもあります。

Function: standard-syntax-table: この関数はFundamentalモードが使用する構文テーブルである、標準構文テーブルをリターンする。

Emacs Lispリーダーは変更不可な独自のビルトイン構文ルールをもつので、構文テーブルは使用しません(いくつかのLispシステムはリード構文を再定義する手段を提供するが、わたしたちは単純化のためこの機能をEmacs Lisp外部に留める決定をした)。

35.2 構文記述子

構文クラス(syntax class)の文字は、その文字の構文的な役割を記述します。各構文テーブルは、それぞれの文字の構文クラスを指定します。ある構文テーブルでの文字のクラスと、別のテーブルにおけるその文字のクラスとの間に関連性がある必要はありません。

Each syntax class is designated by a mnemonic character, which serves as the name of the class when you need to specify a class. Usually, this designator character is one that is often assigned that class; however, its meaning as a designator is unvarying and independent of what syntax that character currently has. Thus, ‘\’ as a designator character always stands for escape character syntax, regardless of whether the ‘\’ character actually has that syntax in the current syntax table. 構文クラスとそれらの指定子文字のリストは、構文クラスのテーブルを参照してください。

構文記述子(syntax descriptor)とは、文字の構文クラスと、その他の構文的なプロパティを記述するLisp文字列のことです。ある文字の構文を変更したい際、それは関数modify-syntax-entryを呼び出して、その引数に構文記述子を渡すことにより行われます(構文テーブルの関数を参照)。

構文記述子の1つ目の文字は、構文クラスの指定子文字でなければなりません。2つ目の文字がもしあれば、マッチング文字を指定します(Lispでは‘(’にたいするマッチング文字は‘)’)。スペースはマッチング文字が存在しないことを指定します。その後に続く文字は、追加の構文プロパティを指定します(構文フラグを参照)。

マッチング文字やフラグが必要なければ、(構文クラスを指定する)1つの文字だけで十分です。

たとえばCモードでの文字‘*’の構文記述子は". 23"(区切り記号、マッチング文字用スロットは未使用、コメント開始記号の2つ目の文字、コメント終了記号の1つ目の文字)、‘/’にたいするエントリーは‘. 14’(区切り記号、マッチング文字用スロットは未使用、コメント開始記号の1つ目の文字、コメント終了記号の2つ目の文字)です。

Emacsは、低レベルでの構文クラスを記述するために使用されるraw構文記述子(raw syntax descriptors)も定義しています。構文テーブルの内部を参照してください。

35.2.1 構文クラスのテーブル

以下は構文クラス、それらの指定子となる文字とそれらの意味、およびそれらの使用例を示すテーブルです。

空白文字: ‘ ’、または‘-’

シンボルおよび単語を区別する文字。空白文字は通常は他の構文的な意義をもたず、複数の空白文字は構文的には単一の空白文字と等しい。スペース、タブ、フォームフィードは、ほとんどすべてのメジャーモードにおいて空白文字にクラスっ分けされる。

この構文クラスは‘ ’または‘-’により指定できる。両指定子は等価である。

単語構成文字: ‘w’

人間の言語における単語の一部。これらは通常は、プログラム内において変数やコマンドの名前として使用される。通常、すべての大文字と小文字、および数字は単語構成文字である。

シンボル構成文字: ‘_’

単語構成文字とともに変数やコマンドの名前で使用される、追加の文字。例としてはLispモードの文字‘$&*+-_<>’が含まれ、これらはたとえ英単語の一部でないとしても、シンボルの名前の一部となり得る。標準Cでは、シンボル内において非単語構成文字で有効な文字はアンダースコア(‘_’)だけである。

区切り文字: ‘.’

人間の言語において句読点として使用される文字、またはプログラミング言語でシンボルを別のシンボルと区別するために使用される文字。Emacs Lispモードのようないくつかのプログラミング言語のモードでは、単語構成文字およびシンボル構成文字のいずれでもないいくつかの文字はすべて、他の用途をもつので、このクラスの文字をもたない。Cモードのような他のプログラミング言語のモードでは、演算子にたいして区切り文字構文が使用される。

開カッコ文字: ‘(’

閉カッコ文字: ‘)’

文や式を囲うために、異なるペアーとして使用される文字。そのようなグループ化は開カッコで開始され、閉カッコで終了する。開カッコ文字はそれぞれ特定の閉カッコ文字にマッチし、その逆も成り立つ。Emacsqは通常、閉カッコ挿入字に、マッチする開カッコを示す。カッコの点滅を参照のこと。

人間の言語、およびCのコードではカッコのペアーは‘()’、‘[]’、‘{}’である。Emacs Lispではリストとベクターにたいする区切り文字(‘()’および‘[]’)は、カッコ文字としてクラス分けされる。

文字列クォート: ‘"’

文字列定数を区切るために使用される文字。文字列の先頭と終端に、同じ文字列クォート文字が出現する。このようなクォート文字列はネストされない。

Emacsのパース機能は、文字列を単一のトークンとみなす。文字列内では、その文字の通常の構文的な意味は抑制される。

The Lisp modes have two string quote characters: double-quote (‘"’) and vertical bar (‘|’). ‘|’ is not used in Emacs Lisp, but it is used in Common Lisp. C also has two string quote characters: double-quote for strings, and apostrophe (‘'’) for character constants.

人間用のテキストには文字列クォート文字がない。そのクォーテーション内の別の文字の通常の構文的プロパティを、クォーテーションマークがオフに切り替えるのを、わたしたちは望まない。

エスケープ構文文字: ‘\’

文字列や文字定数内で使用されるような、エスケープシーケンスで始まる文字。CとLispの両方で、文字‘\’はこのクラスに属する(Cでは文字列内でのみ使用されるが、Cコード中を通じてこのように扱っても問題ないことがわかった)。

words-include-escapesが非nilな、このクラスの文字は単語の一部とみなされる。単語単位の移動を参照のこと。

文字クォート: ‘/’

その文字の通常の構文的な意義を失うよう、後続の文字をクォートするために使用される文字。これは直後に続く文字だけに影響する点が、エスケープ文字と異なる。

words-include-escapesが非nilな、このクラスの文字は単語の一部とみなされる。単語単位の移動を参照のこと。

このクラスはTeXモードのバックスラッシュにたいして使用される。

区切りペアー: ‘$’

文字列クォート文字と似ているが、この区切りの間にある文字の構文的なプロパティは抑制されない点が異なる。現在のところTeXモードだけが区切りペアーを使用する(‘$’によりmathモードに出入りする)。

式プレフィクス: ‘'’

式に隣接して出現した場合に、その式の一部とみなされる、構文的演算子にたいして使用される文字。Lispモードではアポストロフィー‘'’(クォートに使用)、カンマ‘,’(マクロに使用)、‘#’(特定のデータ型にたいするリード構文として使用)が、これらの文字に含まれる。

コメント開始文字: ‘<’

コメント終了文字: ‘>’

さまざまな言語において、コメントを区切るために使用する文字。人間用のテキストはコメント文字をもたない。Lispでは、セミコロン(‘;’)がコメントの開始で、改行かフォームフィードで終了する。

標準構文の継承: ‘@’

この構文クラスは、特定の構文を指定しない。これは、その文字の構文を探すために標準構文テーブルを照合するよう告げる。

汎用コメント区切り: ‘!’

特殊なコメントを開始または終了させる文字。任意の汎用コメント区切りは、任意の汎用コメント区切りにマッチするが、コメント開始とコメント終了とはマッチできない。汎用コメント区切りは、汎用コメント区切り同士としかマッチできない。

この構文クラスは主としてsyntax-tableテキストプロパティ(構文プロパティを参照)とともに使用することを意図している。任意の文字範囲にたいして、その範囲の最初と最後の文字にたいして、それらが汎用コメント区切りであることを示すsyntax-tableプロパティを付与することにより、その範囲がコメントを形成するとマークすることができる。

汎用文字列区切り: ‘|’

文字列を開始または終了させる文字。任意の汎用文字列区切りは、任意の汎用文字列区切りにマッチするが、通常の文字列クォート文字とはマッチできない。

この構文クラスは主としてsyntax-tableテキストプロパティ(構文プロパティを参照)とともに使用することを意図している。任意の文字範囲にたいして、その範囲の最初と最後の文字にたいして、それらが汎用文字列区切りであることを示すsyntax-tableプロパティを付与することにより、その範囲が文字列定数を形成するとマークすることができる。

35.2.2 構文フラグ

構文テーブル内の文字全体にたいして、構文クラスに加えてフラグを指定できます。利用できる8つのフラグがあり、それらは文字‘1’、‘2’、‘3’、‘4’、‘b’、‘c’、‘n’、‘p’で表されます。

‘p’を除くすべてのフラグは、コメント区切りを記述するために使用されます。数字のフラグは2文字から構成されるコメント区切りにたいして使用されます。これらは、文字の文字クラスに関連付けられた構文的プロパティに加えて、その文字も同様にコメントシーケンスの一部となれることを示します。Cモードでは区切り文字であり、かつコメントシーケンス開始(‘/*’)の2文字目であり、かつコメントシーケンス終了(‘*/’)の1文字目である‘*’のような文字のために、フラグとクラスは互いに独立しています。フラグ‘b’、‘c’、‘n’は対応するコメント区切りを限定するために使用されます。

以下は文字cにたいして利用できるフラグと、それらの意味を示すテーブルです:

‘1’は、cが2文字からなるコメント開始シーケンスの開始であることを意味する。
‘2’は、cがそのようなシーケンスの2文字目であることを意味する。
‘3’は、cが2文字からなるコメント終了シーケンスの開始であることを意味する。
‘4’は、cがそのようなシーケンスの2文字目であることを意味する。
‘b’は、cが代替えのコメントスタイル“b”に属するコメント区切りであることを意味する。このフラグは2文字のコメント開始では2文字目、2文字のコメント終了では1文字目にたいしてのみ意味をもつ。
‘c’は、cが代替えのコメントスタイル“c”に属するコメント区切りであることを意味する。2文字からなるコメント区切りにたいしては、そのいずれかが‘c’であればスタイル“c”となる。
‘n’ on a comment delimiter character specifies that this kind of comment can be nested. Inside such a comment, only comments of the same style will be recognized. For a two-character comment delimiter, ‘n’ on either character makes it nestable.
Emacsは任意の構文テーブル1つにたいして、同時に複数のコメントスタイルをサポートする。コメントスタイルはフラグ‘b’、‘c’、‘n’の組み合わせなので、8個の異なるコメントスタイルが可能である。コメント区切りはそれぞれスタイルをもち、同じスタイルのコメント区切りとのみマッチできる。つまりコメントがスタイル“bn”のコメント開始シーケンスで開始されるなら、そのコメントは次のスタイル“bn”のコメント終了シーケンスにマッチするまで拡張されるだろう。

C++にたいして適切なコメント構文は、以下のようになる:

‘/’

‘124’

‘*’

‘23b’

newline

‘>’

これは4つのコメント区切りシーケンスを定義する:

‘/*’

これは2文字目の‘*’が‘b’フラグをもつので、“b”スタイルのコメント開始シーケンスである。

‘//’

これは2文字目の‘/’が‘b’フラグをもたないので、“a”スタイルのコメント開始シーケンスである。

‘*/’

これは1文字目の‘*’が‘b’フラグをもつので、“b”スタイルのコメント終了シーケンスである。

newline

これは改行文字が‘b’フラグをもたないので、“a”スタイルのコメント終了シーケンスである。
‘p’ identifies an additional prefix character for Lisp syntax. These characters are treated as whitespace when they appear between expressions. When they appear within an expression, they are handled according to their usual syntax classes.
関数backward-prefix-charsはこれらの文字と、同様にメインの構文クラスがプレフィクスであるような文字(‘'’)を超えて、後方に移動する。モーションと構文を参照のこと。

35.3 構文テーブルの関数

このセクションでは、構文テーブルを作成、アクセス、変更する関数を説明します。

Function: make-syntax-table &optional table

この関数は、新たに構文テーブルを作成する。tableが非nilなら、新たな構文テーブルの親はtable、それ以外なら標準構文テーブルが親になる。

新たな構文テーブルでは最初は、すべての文字に構文クラス“inherit”(‘@’)が与えられ、それらの構文は親テーブルから継承される(構文クラスのテーブルを参照)。

Function: copy-syntax-table &optional table: この関数はtableのコピーを構築して、それをリターンする。tableが省略またはnilなら、標準構文テーブルのコピーをリターンする。それ以外の場合、tableが構文テーブルでなければエラーをシグナルする。

Command: modify-syntax-entry char syntax-descriptor &optional table

この関数はsyntax-descriptorに応じて、charの構文エントリーをセットする。charは文字、または(min . max)という形式のコンスセルでなければならない。後者の場合、この関数はminとmax(両端を含む)の間のすべての文字にたいして、構文エントリーをセットする。

構文はtable(デフォルトはカレントバッファーの構文テーブル)にたいしてのみ変更され、他のすべての構文テーブルにたいしては変更されない。

引数syntax-descriptorは構文記述子、すなわち1文字目が構文クラス指定子、2文字目以降がオプションでマッチング文字と構文フラグを指定する文字列である。構文記述子を参照のこと。syntax-descriptorが有効な構文記述子でなければ、エラーがシグナルされる。

この関数は、常にnilをリターンする。この文字にたいするテーブル内の古い構文情報は、破棄される。

例:


;; 空白文字クラスのスペースをputする
(modify-syntax-entry ?\s " ")
     ⇒ nil

;; ‘$’を開カッコ文字にして、
;;   ‘^’を対応する閉カッコにする
(modify-syntax-entry ?$ "(^")
     ⇒ nil

;; ‘^’閉カッコ文字にして
;;   ‘$’を対応する開カッコにする
(modify-syntax-entry ?^ ")$")
     ⇒ nil

;; ‘/’を区切り文字で
;;   コメント開始シーケンス1文字目、
;;   かつコメント終了シーケンス2文字目とする
;;   これはCモードで使用される
(modify-syntax-entry ?/ ". 14")
     ⇒ nil

Function: char-syntax character

この関数は、指定子文字(構文クラスのテーブルを参照)の表現で、characterの構文クラスをリターンする。これはクラスだけをリターンし、マッチング文字や構文フラグはリターンしない。

以下をCモードにたいして適用してみる(char-syntaxがリターンする文字を確認しやすいようstringを使用する)。

;; スペース文字は空白文字構文クラスをもつ
(string (char-syntax ?\s))
     ⇒ " "

;; スラッシュ文字は区切り文字構文をもつ。
;; コメント開始やコメント終了シーケンスの一部でもある場合、
;; char-syntax呼び出しはこれを明らかにしないことに注意。
(string (char-syntax ?/))
     ⇒ "."

;; 開カッコ文字は開カッコ構文をもつ。
;; これがまっちんぐ文字‘)’をもつことは
;; char-syntax呼び出しでは明らかにならないことに注意。
(string (char-syntax ?\())
     ⇒ "("

Function: set-syntax-table table: この関数は、カレントバッファーの構文テーブルをtableにする。これはtableをリターンする。

Function: syntax-table: この関数はカレント構文テーブル(カレントバッファーのテーブル)をリターンする。

Command: describe-syntax &optional buffer: このコマンドは、buffer(デフォルトはカレントバッファー)の構文テーブルのコンテンツをhelpバッファーに表示する。

Macro: with-syntax-table table body…

このまくろはtableをカレント構文テーブルとして使用して、bodyを実行する。これは古いカレント構文テーブルのリストア後に、bodyの最後のフォームの値をリターンする。

各バッファーは独自にカレント構文テーブルをもつので、マクロはこれを入念に行う。with-syntax-tableはマクロ実行開始時、そのときカレントのバッファーが何であれ、カレント構文テーブルを一時的に変更する。他のバッファーは影響を受けない。

35.4 構文プロパティ

ある言語の構文を指定するのに構文テーブルが十分に柔軟でないときは、バッファー内に出現する特定の文字にたいして、テキストプロパティsyntax-tableを適用することにより、構文テーブルをオーバーライドできます。テキストプロパティを適用する方法については、テキストのプロパティを参照してください。

以下はテキストプロパティsyntax-tableの有効な値です:

syntax-table: プロパティの値が構文テーブルなら、根底となるテキスト文字の構文を決定するカレントバッファーの構文テーブルのかわりに、そのテーブルが使用される。
(syntax-code . matching-char): この形式のコンスセルは、根底となるテキスト文字の構文クラスを直接指定する、raw構文テーブル(構文テーブルの内部を参照)である。
nil: このプロパティがnilなら、その文字の構文はカレント構文テーブルにより通常の方法で決定される。

Variable: parse-sexp-lookup-properties: これが非nilなら、forward-sexpのような構文をスキャンする関数は、syntax-tableテキストプロパティに注意を払い、それ以外ならカレント構文テーブルだけを使用する。

Variable: syntax-propertize-function

この変数が非nilなら、特定のテキスト範囲にたいしてsyntax-tableプロパティを適用する関数を格納するべきである。これは、モードに適した方法でsyntax-tableプロパティを適用する関数をインストールするために、メジャーモードに使用されることを意図している。

この関数はsyntax-ppss(ある位置のパース状態を調べるを参照)、および構文フォント表示化(構文的なFont Lockを参照)の間にFont Lockモードにより呼び出される。これは作用すべきテキスト部分の開始startと終了endという、2つの引数で呼び出される。これはendの前の任意の位置で、syntax-ppssを呼び出すことが許されている。しかしsyntax-ppss-flush-cacheを呼び出すべきではなく、そのため、ある位置でsyntax-ppssを呼び出して、後からバッファー内の前の位置を変更することは許されていない。

Variable: syntax-propertize-extend-region-functions

このアブノーマルフックはsyntax-propertize-function呼び出しに先立ち、構文解析コードにより実行される。これはsyntax-propertize-functionに渡すための、安全なバッファーの開始および終了位置を見つける助けをする役割をもつ。たとえばメジャーモードは、複数行の構文構成を識別して、境界が複数行の中間にならないよう、このフックに関数を追加できる。

このフック内の各関数は、引数startとendを受け取ること。これは2つのバッファー位置を調整するコンスセル(new-start . new-end)、調整が必要なければnilをリターンするべきである。フック関数は、それらすべてがnilをリターンするまで、順番に繰り返し実行される。

35.5 モーションと構文

このセクションでは、特定の構文クラスをもつ文字間を横断して移動する関数を説明します。

Function: skip-syntax-forward syntaxes &optional limit

この関数は、syntaxesで指定された構文クラス(構文クラスの文字列)をもつ文字を横断して、ポイントを前方に移動する。バッファー終端か、(与えられた場合は)位置limitに到達、またはスキップしない文字に達した際に停止する。

syntaxesが‘^’で始まる場合、この関数は構文がsyntaxesではない文字をスキップする。

リターン値は、移動した距離を表す非負の整数。

Function: skip-syntax-backward syntaxes &optional limit

この関数は、syntaxesで指定された構文クラスをもつ文字を横断して、ポイントを後方に移動する。バッファー先頭か、(与えられた場合は)位置limitに到達、またはスキップしない文字に達した際に停止する。

syntaxesが‘^’で始まる場合、この関数は構文がsyntaxesではない文字をスキップする。

リターン値は、移動した距離を表す0以下の整数。

Function: backward-prefix-chars: この関数は、式プレフィクス構文の任意個数の文字を横断して、後方にポイントを移動する。これには式プレフィクス構文クラスと、フラグ‘p’の文字の両方が含まれる。

35.6 式のパース

This section describes functions for parsing and scanning balanced expressions. We will refer to such expressions as sexps, following the terminology of Lisp, even though these functions can act on languages other than Lisp. Basically, a sexp is either a balanced parenthetical grouping, a string, or a symbol (i.e., a sequence of characters whose syntax is either word constituent or symbol constituent). However, characters in the expression prefix syntax class (see section 構文クラスのテーブル) are treated as part of the sexp if they appear next to it.

構文テーブルは文字の解釈を制御するので、これらの関数はLispモードでのLisp式、CモードでのCの式にたいして使用できます。バランスのとれた式にたいする、有用な高レベル関数については、バランスのとれたカッコを越えた移動を参照してください。

A character’s syntax controls how it changes the state of the parser, rather than describing the state itself. For example, a string delimiter character toggles the parser state between in-string and in-code, but the syntax of characters does not directly say whether they are inside a string. For example (note that 15 is the syntax code for generic string delimiters),

(put-text-property 1 9 'syntax-table '(15 . nil))

これはEmacsにたいして、カレントバッファーの最初の8文字が文字列であることを告げますが、それらはすべて文字列区切りです。結果としてEmacsはそれらを、連続する4つの空文字列定数として扱います。

35.6.1 パースにもとづくモーションコマンド

このセクションでは、式のパースにもとづいて処理を行う、シンプルなポイント移動関数を説明します。

Function: scan-lists from count depth

この関数は、位置fromからバランスのとれたカッコのグループをcount個、前方にスキャンする。これはスキャンが停止した位置をリターンする。countが負なら、スキャンは後方に移動する。

depthが非0なら、開始位置のカッコのネスト深さをdepthとして扱う。スキャナーは、ネスト深さが0になるまでcount回、繰り返し前方または後方に移動する。そのため、正のdepthは開始位置からカッコをdepthレベル抜け出して移動する効果があり、負のdepthはカッコがdepthレベル深くなるよう移動する効果をもつ。

parse-sexp-ignore-commentsが非nilなら、スキャンはコメントを無視する。

count個のカッコのグループをスキャンする前に、スキャンがバッファーのアクセス可能範囲の先頭か終端に達した場合、そのポイントのネスト深さが0なら、値nilをリターンする。ネスト深さが非0なら、scan-errorエラーをシグナルする。

Function: scan-sexps from count

この関数は位置fromから、count個のsexpを前方にスキャンする。これは、スキャンが停止した位置をリターンする。countが負なら、スキャンは後方へ移動する。

parse-sexp-ignore-commentsが非nilなら、スキャンはコメントを無視する。

カッコのグループの中間でバッファー(のアクセス可能範囲)の先頭か終端に達した場合は、エラーをシグナルする。count個を消費する前に、カッコのグループの間でバッファーの先頭か終端に達した場合は、nilをリターンする。ネスト深さが非0なら、scan-errorエラーをシグナルする。

Function: forward-comment count

この関数は、count個の完全なコメント(すなわち、もしあれば開始区切りと終了区切りを含む)、および途中で遭遇する任意の空白文字を横断して、ポイントを前方に移動する。countが負なら、後方に移動する。コメントまたは空白文字以外のものに遭遇したら停止して、その停止位置にポイントを残す。これには、(たとえば)前方に移動してコメント開始を調べる際に、コメント終了を探すことも含まれる。この関数は、指定された個数の完全なコメントを横断して移動した後も、即座に停止する。空白以外のものがコメント間に存在せずに、期待どおりcount個のコメントが見つかったらtを、それ以外はnilをリターンする。

This function cannot tell whether the comments it traverses are embedded within a string. If they look like comments, it treats them as comments.

ポイント後のすべてのコメントと空白文字を飛び越して移動するには、(forward-comment (buffer-size))を使用する。バッファー内のコメント数は(buffer-size)を超えることはできないので、これは引数としての使用に適す。

35.6.2 ある位置のパース状態を調べる

インデントのような構文分析にとっては、与えられたバッファー位置に応じた構文状態の計算が有用なことが多々あります。それを手軽に行うのが、この関数です。

Function: syntax-ppss &optional pos

This function returns the parser state that the parser would reach at position pos starting from the beginning of the visible portion of the buffer. パーサー状態の説明は、パーサー状態を参照のこと。

The return value is the same as if you call the low-level parsing function parse-partial-sexp to parse from the beginning of the visible portion of the buffer to pos (see section 低レベルのパース). However, syntax-ppss uses caches to speed up the computation. Due to this optimization, the second value (previous complete subexpression) and sixth value (minimum parenthesis depth) in the returned parser state are not meaningful.

この関数は、syntax-ppss-flush-cache(以下参照)にたいして、before-change-functions(フックの変更を参照)にバッファーローカルなエントリーを追加するという副作用をもつ。このエントリーは、バッファー変更にたいして、キャッシュの一貫性を保つ。とはいえ、before-change-functionsが一時的にletでバインドされている間にsyntax-ppssが呼び出された場合、またはinhibit-modification-hooks使用時のようにバッファーがフックを実行せずに変更される場合、キャッシュは更新されないかもしれない。そのような場合は、明示的にsyntax-ppss-flush-cacheを呼び出す必要がある。

Function: syntax-ppss-flush-cache beg &rest ignored-args: この関数は、syntax-ppssが使用するキャッシュを、位置begからフラッシュする。残りの引数ignored-argsは無視される。before-change-functions(フックの変更を参照)のような関数で直接使用できるよう、この関数はそれらの引数を受け入れる。

35.6.3 パーサー状態

A parser state is a list of (currently) eleven elements describing the state of the syntactic parser, after it parses the text between a specified starting point and a specified end point in the buffer. Parsing functions such as syntax-ppss (ある位置のパース状態を調べるを参照) は、値としてパーサー状態をリターンします。いくつかのパース関数は、パースを再開するために、引数としてパーサー状態を受け取ります。

以下は、パーサー状態の要素の意味です:

0から数えたカッコの深さ。警告: パーサーの開始位置と終了位置の間に開カッコより多くの閉カッコがあれば、負になることもある。
停止位置を含む最内のカッコグループの開始文字位置。なければnil。
最後の終端された完全な部分式の開始文字位置。なければnil。
文字列内部なら非nil。より正確には、文字列を終端させるであろう文字か、汎用文字列区切りが終端すべきような場合はtとなる。
ネスト不可なコメント(または任意のコメントスタイル。構文フラグを参照されたい)の内部ならt、ネスト可なコメントの内部ならコメントのネストレベル。
終了位置がクォート文字直後ならt。
当該スキャン中に遭遇した最小のカッコ深さ。
アクティブなコメントの種類。コメント以外、またはスタイル‘a’のコメント内ならnil、スタイル‘b’のコメントなら1、スタイル‘c’のコメントなら2、汎用コメント区切り文字で終端されるべきコメントならsyntax-table。
文字列またはコメントの開始位置。コメント内部ならコメントが始まる位置。文字列内部なら文字列が始まる位置。文字列またはコメントの外部なら、この要素はnilになる。
The list of the positions of the currently open parentheses, starting with the outermost.
When the last buffer position scanned was the (potential) first character of a two character construct (comment delimiter or escaped/char-quoted character pair), the syntax-code (see section 構文テーブルの内部) of that position. Otherwise nil.

Elements 1, 2, and 6 are ignored in a state which you pass as an argument to continue parsing. Elements 9 and 10 are mainly used internally by the parser code.

以下の関数を使用することにより、さらに追加でパーサー状態から有用な情報を利用できます:

Function: syntax-ppss-toplevel-pos state

この関数はパーサー状態stateから、文法構造上トップレベルでのパースにおける、スキャンした最後の位置をリターンする。“トップレベル”とは、すべてのカッコ、コメント、文字列の外部であることを意味する。

stateがトップレベルの位置に到達したパースを表す場合、値はnilとなる。

35.6.4 低レベルのパース

式パーサーを使用するもっとも基本的な方法は、特定の状態で与えられた位置からパースを開始して、指定した位置でパースを終了するよう指示する方法です。

Function: parse-partial-sexp start limit &optional target-depth stop-before state stop-comment

この関数は、カレントバッファー内のsexpを、startから開始してlimitを超えてスキャンしないようパースを行う。これは位置limit、または以下に記述する特定の条件に適合したら停止して、パースが停止した位置にポイントをセットする。これはポイントが停止した位置でのパースの状態を記述するパーサー状態をリターンする。

3つ目の引数target-depthが非nilの場合、カッコの深さがtarget-depthと等しくなったら、パースを停止する。この深さは0、またはstate内で与えられる深さなら何であれ、そこより開始される。

If the fourth argument stop-before is non-nil, parsing stops when it comes to any character that starts a sexp. If stop-comment is non-nil, parsing stops after the start of an unnested comment. If stop-comment is the symbol syntax-table, parsing stops after the start of an unnested comment or a string, or after the end of an unnested comment or a string, whichever comes first.

stateがnilなら、startは関数定義先頭のような、カッコ構造のトップレベルであるとみなされる。かわりにこの構造の中間でパースを再開したいと思うかもしれない。これを行うには、パースの初期状態を記述するstate引数を提供しなければならない。前のparse-partial-sexp呼び出しでリターンされた値で、これをうまく行うことができるだろう。

35.6.5 パースを制御するためのパラメーター

Variable: multibyte-syntax-as-symbol: この変数が非nilなら、構文テーブルがそれらについて何と言っているかに関わらず、scan-sexpsはすべての非ASCII文字をシンボル構成要素として扱う(とはいえ依然としてテキストプロパティは構文をオーバーラードできるが)。

User Option: parse-sexp-ignore-comments: この値が非nilなら、このセクション内の関数、およびforward-sexp、scan-lists、scan-sexpsはコメントを空白文字として扱う。

parse-partial-sexpの振る舞いも、parse-sexp-lookup-propertiesの影響を受けます(構文プロパティを参照)。

Variable: comment-end-can-be-escaped: If this buffer local variable is non-nil, a single character which usually terminates a comment doesn’t do so when that character is escaped. This is used in C and C++ Modes, where line comments starting with ‘//’ can be continued onto the next line by escaping the newline with ‘\’.

1つ、または複数のコメントを横断して前方または後方に移動するには、forward-commentを使用できます。

35.7 構文テーブルの内部

構文テーブルは文字テーブル(文字テーブルを参照)として実装されていますが、ほとんどのLispプログラムが直接それらの要素に作用することはありません。構文テーブルは構文データとして構文記述子を格納しません(構文記述子を参照)。それらは内部的なフォーマットを使用しており、それについてはこのセクションで説明します。この内部的フォーマットは、構文プロパティとして割り当てることもできます(構文プロパティを参照)。

構文テーブル内の各要素はraw構文記述子(raw syntax descriptor)という、(syntax-code . matching-char)という形式のコンスセルです。syntax-codeは、下記のテーブルに応じて構文クラスと構文フラグをエンコードする整数です。matching-charが非nilなら、それはマッチング文字(構文記述子内の2つ目の文字と同様)を指定します。

Use aref (see section 配列を操作する関数) to get the raw syntax descriptor of a character, e.g. (aref (syntax-table) ch).

以下は、さまざまな構文クラスに対応する構文コードです。

Code	Class	Code	Class
0	空白文字	8	区切り文字ペアー
1	句読点	9	エスケープ
2	単語	10	文字クォート
3	シンボル	11	コメント開始
4	開カッコ	12	コメント終了
5	閉カッコ	13	継承
6	式プレフィクス	14	汎用コメント
7	文字列クォート	15	汎用文字列

たとえば標準構文テーブルでは、‘(’にたいするエントリーは(4 . 41)であり、41は‘)’の文字コードです。

構文フラグは、最下位ビットから16ビット目より始まる、高位ビットにエンコードされます。以下のテーブルは、対応する各構文フラグにたいして、2のべき乗を与えます。

Prefix	Flag	Prefix	Flag
‘`1`’	`(lsh 1 16)`	‘`p`’	`(lsh 1 20)`
‘`2`’	`(lsh 1 17)`	‘`b`’	`(lsh 1 21)`
‘`3`’	`(lsh 1 18)`	‘`n`’	`(lsh 1 22)`
‘`4`’	`(lsh 1 19)`	‘`c`’	`(lsh 1 23)`

Function: string-to-syntax desc: 与えられた構文記述子desc(文字列)にたいして、この関数は対応するraw構文記述子をリターンする。

Function: syntax-after pos: この関数は、バッファー内の位置posの後の文字にたいして、構文テーブルと同様に構文プロパティも考慮した、raw構文記述子をリターンする。posがバッファーのアクセス可能範囲(accessible portionを参照)の外部なら、リターン値はnilとなる。

Function: syntax-class syntax

この関数はraw構文記述子syntaxにたいする、構文コードをリターンする。より正確には、これはraw構文記述子のsyntax-code要素から、構文フラグを記録する高位16ビットをマスクして、その結果の整数をリターンする。

syntaxがnilなら、リターン値はnilとなる。これは以下の式

(syntax-class (syntax-after pos))

は、posがバッファーのアクセス可能範囲外部なら、エラーをthrowしたり不正なコードをリターンすることなく、nilに評価されるからである。

35.8 カテゴリー

カテゴリー(categories)は、構文的に文字をクラス分けする別の手段を提供します。必要に応じて複数のカテゴリーを定義して、それぞれの文字に独立して1つ以上のカテゴリーを割り当てることができます。構文クラスと異なり、カテゴリーは互いに排他ではありません。1つの文字が複数のカテゴリーに属すのは、普通のことです。

バッファーはそれぞれカテゴリーテーブル(category table)をもっています。これはどのカテゴリーが定義されていて、各カテゴリーにどの文字が属すかを記録しています。カテゴリーテールは自身のカテゴリーを定義しますが、標準カテゴリーはすべてのモードで利用可能なので、通常これらは標準カテゴリーテーブルをコピーすることにより初期化されます。

カテゴリーはそれぞれ、‘ ’から‘~’の範囲のASCIIプリント文字による名前をもちます。define-categoryで定義する際は、カテゴリーの名前を指定します。

カテゴリーテーブルは、実際には文字テーブルです(文字テーブルを参照)。カテゴリーテーブルのインデックスcの要素は、文字cが属するカテゴリーを示すカテゴリーセット(category set)というブールベクターです。このカテゴリーセット内で、もしインデックスcatの要素がtなら、catはそのセットのメンバーであり、その文字cはカテゴリーcatに属することを意味します。

以下の3つの関数では、オプション引数tableのデフォルトはカレントバッファーのカテゴリーテーブルです。

Function: define-category char docstring &optional table

この関数はカテゴリーテーブルtableにたいして、名前がchar、ドキュメントがdocstringであるような、新たなカテゴリーを定義する。

Here’s an example of defining a new category for characters that have strong right-to-left directionality (see section 双方向テキストの表示) and using it in a special category table. To obtain the information about the directionality of characters, the example code uses the ‘bidi-class’ Unicode property (see section bidi-class).

(defvar special-category-table-for-bidi
  ;;     Make an empty category-table.
  (let ((category-table (make-category-table))
        ;; Create a char-table which gives the 'bidi-class' Unicode
        ;; property for each character.
        (uniprop-table
         (unicode-property-table-internal 'bidi-class)))
    (define-category ?R "Characters of bidi-class R, AL, or RLO"
                     category-table)
    ;; Modify the category entry of each character whose
    ;; 'bidi-class' Unicode property is R, AL, or RLO --
    ;; these have a right-to-left directionality.
    (map-char-table
     #'(lambda (key val)
         (if (memq val '(R AL RLO))
             (modify-category-entry key ?R category-table)))
     uniprop-table)
    category-table))

Function: category-docstring category &optional table

この関数は、カテゴリーテーブルtable内のカテゴリーcategoryの、ドキュメント文字列をリターンする。

(category-docstring ?a)
     ⇒ "ASCII"
(category-docstring ?l)
     ⇒ "Latin"

Function: get-unused-category &optional table: この関数は、table内で現在のところ未定義なカテゴリーの名前(文字)をリターンする。table内で利用可能なカテゴリーがすべて使用済みなら、nilをリターンする。

Function: category-table: この関数は、カレントバッファーのカテゴリーテーブルをリターンする。

Function: category-table-p object: この関数は、objectがカテゴリーテーブルならt、それ以外はnilをリターンする。

Function: standard-category-table: この関数は、標準カテゴリーテーブルをリターンする。

Function: copy-category-table &optional table: この関数は、tableのコピーを構築して、それをリターンする。tableが与えられない(またはnil)場合は、標準カテゴリーテーブルのコピーをリターンする。それ以外の場合は、もしtableがカテゴリーテーブルでなければ、エラーをシグナルする。

Function: set-category-table table: この関数は、tableをカレントバッファーのカテゴリーテーブルにする。リターン値はtable。

Function: make-category-table: これは空のカテゴリーテーブルを作成してリターンする。 This creates and returns an empty category table. 空のカテゴリーテーブルでは、どのカテゴリーも割り当てられておらず、何らかのカテゴリーに属する文字もない。

Function: make-category-set categories

この関数は、初期内容が文字列categoriesにリストされるカテゴリーであるような、新たなカテゴリーセット(ブールベクター)をリターンする。categoriesの要素はカテゴリー名であること。新たなカテゴリーセットはそれらのカテゴリーにたいしてt、それ以外のすべてのカテゴリーにたいしてnilをもつ。

(make-category-set "al")
     ⇒ #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"

Function: char-category-set char

この関数は、カレントバッファーのカテゴリーテーブル内で、文字charにたいするカテゴリーセットをリターンする。これは文字charが属するカテゴリーを記録するブールベクターである。関数char-category-setは、カテゴリーテーブル内にある同じブールベクターをリターンするので、メモリーの割り当ては行わない。

(char-category-set ?a)
     ⇒ #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"

Function: category-set-mnemonics category-set

この関数は、カテゴリーセットcategory-setを、そのセットのメンバーのカテゴリーを指定する文字を含む文字列に変換する。

(category-set-mnemonics (char-category-set ?a))
     ⇒ "al"

Function: modify-category-entry char category &optional table reset

この関数は、カテゴリーテーブルtable(デフォルトはカレントバッファーのカテゴリーテーブル)内の、charのカテゴリーセットを変更する。charには文字、または(min . max)という形式のコンスセルを指定できる。後者の場合、この関数はminとmaxの間(両端を含む)の範囲にある、すべての文字のカテゴリーセットを変更する。

これは通常、カテゴリーセットにcategoryを追加することにより、変更を行う。しかしresetが非nilなら、かわりにcategoryを削除する。

Command: describe-categories &optional buffer-or-name: この関数は、カレントカテゴリーテーブル内のカテゴリー仕様を説明する。これはその説明をバッファーに挿入してから、そのバッファーを表示する。buffer-or-nameが非nilなら、かわりにそのバッファーのカテゴリーテーブルを説明する。

36 abbrevとabbrev展開

略語(abbreviation)、またはabbrevは、より長い文字列へと展開される文字列です。ユーザーはabbrev文字列を挿入して、それを探して自動的にabbrevの展開形に置換できます。これによりタイプ量を節約できます。

カレントで効果をもつabbrevsのセットは、abbrevテーブル(abbrev table)内に記録されます。バッファーはそれぞれローカルにabbrevテーブルをもちますが、通常は同一のメジャーモードにあるすべてのバッファーが1つのabbrevテーブルを共有します。グローバルabbrevテーブルも存在します。通常は両者が使用されます。

abbrevテーブルはobarrayとして表されます。obarraysについての情報は、シンボルの作成とinternを参照してください。,abbrevはそれぞれ、obarray内のシンボルとして表現されます。そのシンボルの名前がabbrevで、値が展開形になります。シンボルの関数定義は展開を行うフック関数です(abbrevの定義を参照)。また、シンボルノプロパティセルには、使用回数やそのabbrevが展開された回数を含む、さまざまな追加プロパティが含まれます(abbrevプロパティーを参照)。

システムabbrev(system abbrevs)と呼ばれる特定のabbrevは、ユーザーではなくメジャーモードにより定義されます。システムabbrevは、非nilの:systemプロパティにより識別されます(abbrevプロパティーを参照)。abbrevがabbrevファイルに保存される際、システムabbrevは省略されます。ファイルへのabbrevの保存を参照してください。

abbrevに使用されるシンボルは通常のobarrayにinternされないので、Lisp式の読み取り結果として現れることは決してありません。実際に、通常はabbrevを扱うコードを除き、それらが使用されることはありません。したがって、それらを非標準的な方法で使用しても安全なのです。

マイナーモードであるAbbrevモードが有効な場合、バッファーローカル変数abbrev-modeは非nilとなり、そのバッファー内で、abbrevは自動的に展開されます。abbrev用のユーザーレベルのコマンドについては、Abbrev Mode in The GNU Emacs Manualを参照してください。

36.1 abbrevテーブル		abbrevテーブルの作成と操作。
36.2 abbrevの定義		略語の指定とそれらの展開。
36.3 ファイルへのabbrevの保存
36.4 略語の照会と展開		展開の制御と展開サブルーチン。
36.5 標準的なabbrevテーブル		種々メジャーモードに使用されるabbrevテーブル。
36.6 abbrevプロパティー		abbrevプロパティの読み取りとセットを行う方法。どのプロパティが何の効果をもつか。
36.7 abbrevテーブルのプロパティー		abbrevテーブルプロパティの読み取りとセットを行う方法。どのプロパティが効果をもつか。

36.1 abbrevテーブル

このセクションでは、abbrevテーブルの作成と操作を行う方法について説明します。

Function: make-abbrev-table &optional props: この関数は、空のabbrevテーブル(シンボルを含まないobarray)を作成してリターンする。これは0で充填されたベクターである。propsは、新たなテーブルに適用されるプロパティリストである(abbrevテーブルのプロパティーを参照)。

Function: abbrev-table-p object: この関数は、objectがabbrevテーブルなら、非nilをリターンする。

Function: clear-abbrev-table abbrev-table: この関数は、abbrev-table内のabbrevをすべて未定義とし、空のまま残す。

Function: copy-abbrev-table abbrev-table: この関数は、abbrev-tableのコピー(同じabbrev定義を含む新たなabbrevテーブル)をリターンする。これは名前、値、関数だけをコピーし、プロパティリストは何もコピーしない。

Function: define-abbrev-table tabname definitions &optional docstring &rest props

この関数はabbrevテーブル名(値がabbrevテーブルであるような変数)としてtabname(シンボル)を定義する。これは、そのテーブル内にdefinitionsに応じて、abbrevを定義する。definitionsは、(abbrevname expansion [hook] [props...])という形式の要素をもつリストである。これらの要素は引数として、define-abbrevに渡される。

オプション文字列docstringは、変数tabnameのドキュメント文字列である。プロパティリストpropsは、abbrevテーブルに適用される(abbrevテーブルのプロパティーを参照)。

同一のtabnameにたいしてこの関数が複数回呼び出された場合は、元のコンテンツ全体を上書きせずに、後続の呼び出しはdefinitions内の定義をtabnameに追加する(後続の呼び出しでは、definitions内で明示的に再定義または未定義にした場合のみabbrevを上書きできる)。

Variable: abbrev-table-name-list: これは、値がabbrevテーブルであるようなシンボルのリストである。define-abbrev-tableは、このリストに新たなabbrevテーブル名を追加する。

Function: insert-abbrev-table-description name &optional human

この関数は、ポイントの前に名前がnameのabbrevテーブルの説明を挿入する。引数nameは、値がabbrevテーブルであるようなシンボルである。

humanが非nilなら、説明は人間向けになる。システムabbrevはそのようにリストされ、識別される。それ以外なら説明はLisp式(カレントで定義されているようにnameを定義するが、システムabbrevとしては定義しないようなdefine-abbrev-table呼び出し)となる(nameを使用するモードまたはパッケージは、それらを個別にnameに追加すると想定されている)。

36.2 abbrevの定義

define-abbrevは、abbrevテーブル内にabbrevを定義するための基本的な低レベル関数です。

When a major mode defines a system abbrev, it should call define-abbrev and specify t for the :system property. Be aware that any saved non-system abbrevs are restored at startup, i.e., before some major modes are loaded. Therefore, major modes should not assume that their abbrev tables are empty when they are first loaded.

Function: define-abbrev abbrev-table name expansion &optional hook &rest props

This function defines an abbrev named name, in abbrev-table, to expand to expansion and call hook, with properties props (see section abbrevプロパティー). The return value is name. The :system property in props is treated specially here: if it has the value force, then it will overwrite an existing definition even for a non-system abbrev of the same name.

name should be a string. The argument expansion is normally the desired expansion (a string), or nil to undefine the abbrev. If it is anything but a string or nil, then the abbreviation expands solely by running hook.

引数hookは、関数またはnilであること。hookが非nilなら、abbrevがexpansionに置換された後に、引数なしでそれが呼び出される。hook呼び出し時、ポイントはexpansionの終端に置かれる。

hookが、no-self-insertプロパティが非nilであるような、非nilのシンボルなら、hookは展開をトリガーするような自己挿入入力文字を挿入できるかどうかを、明示的に制御できる。この場合、hookが非nilをリターンしたら、その文字の挿入を抑止する。対照的に、hookがnilをリターンした場合は、あたかも実際には展開が行われなかったかのように、expand-abbrev(またはabbrev-insert)もnilをリターンする。

通常define-abbrevは、実際にabbrevを変更した場合は、変数abbrevs-changedにtをセットする。これはいくつかのコマンドが、abbrevの保存を提案するためである。システムabbrevは、いずれにせよ保存されないので、システムabbrevにたいして、これは行われない。

User Option: only-global-abbrevs: この変数が非nilなら、それはユーザーがグローバルabbrevのみの使用を計画していることを意味する。これはモード固有のabbrevを定義するコマンドにたいして、かわりにグローバルabbrevを定義するよう指示する。この変数は、このセクション内の関数の振る舞いを変更しない。それは呼び出し側により検証される。

36.3 ファイルへのabbrevの保存

abbrev定義が保存されたファイルは、実際にはLispコードのファイルです。abbrevは、同じコンテンツの同じabbrevテーブルを定義する、Lispプログラムの形式で保存されます。したがってそのファイルは、loadでロードすることができます(プログラムがロードを行う方法を参照)。しかし、より簡便なインターフェースとして、関数quietly-read-abbrev-fileが提供されています。起動時に、Emacsは自動的にこの関数を呼び出します。

save-some-buffersのようなユーザーレベルの機能は、ここで説明する変数の制御下で、自動的にabbrevをファイルに保存できます。

User Option: abbrev-file-name: This is the default file name for reading and saving abbrevs. By default, Emacs will look for ~/.emacs.d/abbrev_defs, and, if not found, for ~/.abbrev_defs; if neither file exists, Emacs will create ~/.emacs.d/abbrev_defs.

Function: quietly-read-abbrev-file &optional filename

この関数は、以前にwrite-abbrev-fileで書き込まれた、filenameという名前のファイルから、abbrevの定義を読み込む。filenameが省略またはnilなら、abbrev-file-name内で指定されているファイルが使用される。

その名前が暗示するように、この関数は何のメッセージも表示しない。

User Option: save-abbrevs: A non-nil value for save-abbrevs means that Emacs should offer to save abbrevs (if any have changed) when files are saved. If the value is silently, Emacs saves the abbrevs without asking the user. abbrev-file-name specifies the file to save the abbrevs in. The default value is t.

Variable: abbrevs-changed: この変数は、abbrev(システムabbrevを除く)の定義または変更によりセットされる。これは、さまざまなEmacsコマンドにとって、ユーザーにabbrevの保存を提案するための、フラグとしての役目をもつ。

Command: write-abbrev-file &optional filename: abbrev-table-name-list内にリストされたすべてのabbrevテーブルにたいして、すべてのabbrev定義(システムabbrevを除く)を、ロード時に同じabbrevを定義するであろうLispプログラム形式で、ファイルfilename内に保存する。filenameがnilなら、abbrev-file-nameが仕様される。この関数はnilをリターンする。

36.4 略語の照会と展開

abbrevは通常、self-insert-commandを含む、特定のinteractiveなコマンドにより展開されます。このセクションでは、そのようなコマンドの記述に使用されるサブルーチン、並びに通信のために使用される変数について説明します。

Function: abbrev-symbol abbrev &optional table: この関数は、abbrevという名前のabbrevを表すシンボルをリターンする。そのabbrevが定義されていなければ、nilをリターンする。オプションの2つ目の引数tableは、それを照合するためのabbrevテーブルである。tableがnilなら、この関数はまずカレントバッファーのローカルabbrevテーブル、次にグローバルabbrevテーブルを試みる。

Function: abbrev-expansion abbrev &optional table: この関数は、abbrevが展開されるであろう文字列(カレントバッファーにたいして使用されるabbrevテーブルで定義される文字列)をリターンする。これはabbrevが有効なabbrevでなければ、nilをリターンする。オプション引数tableはabbrev-symbolの場合と同様、使用するabbrevテーブルを指定する。

Command: expand-abbrev

このコマンドは、(もしあれば)ポイントの前のabbrevを展開する。ポイントがabbrevの後になければ、このコマンドは何もしない。展開を行うために、これは変数abbrev-expand-functionの値となっている関数を引数なしで呼び出し、何であれその関数がリターンしたものをリターンする。

デフォルトの展開関数は、展開を行ったらabbrevのシンボル、それ以外はnilをリターンする。そのabbrevシンボルが、no-self-insertプロパティが非nilのシンボルであるようなフック関数をもち、そのフック関数が値としてnilをリターンした場合は、たとえ展開が行われたとしても、デフォルト展開関数はnilをリターンする。

Function: abbrev-insert abbrev &optional name start end: This function inserts the abbrev expansion of abbrev, replacing the text between start and end. If start is omitted, it defaults to point. name, if non-nil, should be the name by which this abbrev was found (a string); it is used to figure out whether to adjust the capitalization of the expansion. The function returns abbrev if the abbrev was successfully inserted, otherwise it returns nil.

Command: abbrev-prefix-mark &optional arg

このコマンドは、ポイントのカレント位置を、abbrevの開始としてマークする。expand-abbrevの次回呼び出しでは、通常のように以前の単語ではなく、ここからポイント(その時点での位置)にあるテキストが展開するべきabbrevとして使用される。

このコマンドはまず、argがnilなら、ポイントの前の任意のabbrevを展開する(インタラクティブな呼び出しでは、argはプレフィクス引数である)。それから、展開する次のabbrevの開始を示すために、ポイントの前にハイフンを挿入する。実際の展開では、ハイフンは削除される。

User Option: abbrev-all-caps: これが非nilにセットされているときは、すべて大文字で入力されたabbrevは、すべて大文字を使用して展開される。それ以外なら、すべて大文字で入力されたabbrevは、展開形の単語ごとにcapitalizeして展開される。

Variable: abbrev-start-location: この変数の値は、次にabbrevを展開する開始位置としてexpand-abbrevに使用される、バッファー位置である。値はnilも可能で、かわりにポイントの前の単語を使用することを意味する。abbrev-start-locationは、expand-abbrevの呼び出しごとに、毎回nilにセットされる。この変数は、abbrev-prefix-markによってもセットされる。

Variable: abbrev-start-location-buffer: この変数の値は、abbrev-start-locationがセットされたバッファーである。他のバッファーでabbrev展開を試みることにより、abbrev-start-locationはクリアーされる。この変数は、abbrev-prefix-markによりセットされる。

Variable: last-abbrev: これは、直近のabbrev展開のabbrev-symbolである。これは、unexpand-abbrevコマンド(Expanding Abbrevs in The GNU Emacs Manualを参照)のために、expand-abbrevにより残された情報である。

Variable: last-abbrev-location: これは、直近の.abbrev展開の場所である。これには、unexpand-abbrevコマンドのためにexpand-abbrevにより残された情報が含まれる。

Variable: last-abbrev-text: これは直近のabbrev展開の正確な展開形を、(もしあれば)大文字小文字変換した後のテキストである。そのabbrevがすでに非展開されていれば、値はnilになる。これにはunexpand-abbrevコマンドのために、expand-abbrevにより残された情報が含まれる。

Variable: abbrev-expand-function: この変数の値は、展開を行うためにexpand-abbrevが引数なしで呼び出すであろう関数である。この関数では、展開を行う前後に行いたいことを行うことができる。展開が行われた場合は、そのabbrevシンボルをリターンすること。

以下のサンプルコードで、abbrev-expand-functionのシンプルな使い方を示します。このサンプルでは、foo-modeが‘#’で始まる行がコメントであるような、特定のファイルを編集するためのモードであるとします。それらコメント行にたいしては、Textモードのabbrevの使用が望ましく、その他すべての行にたいしては、正規のローカルabbrevテーブルfoo-mode-abbrev-tableが適しています。local-abbrev-tableとtext-mode-abbrev-tableの定義については、標準的なabbrevテーブルを参照してください。add-functionについての詳細は、Emacs Lisp関数にたいするアドバイスを参照してください。

(defun foo-mode-abbrev-expand-function (expand)
  (if (not (save-excursion (forward-line 0) (eq (char-after) ?#)))
      ;; 通常の展開を行う
      (funcall expand)
    ;; コメント内はtext-modeのabbrevを使用
    (let ((local-abbrev-table text-mode-abbrev-table))
      (funcall expand))))

(add-hook 'foo-mode-hook
          #'(lambda ()
              (add-function :around (local 'abbrev-expand-function)
                            #'foo-mode-abbrev-expand-function)))

36.5 標準的なabbrevテーブル

以下は、Emacsの事前ロードされるメジャーモード用のabbrevテーブルを保持する変数のリストです。

Variable: global-abbrev-table: これは、モード非依存なabbrev用のabbrevテーブルである。この中で定義されるabbrevは、すべてのバッファーに適用される。各バッファーはローカルabbrevテーブルももつかもしれず、それのabbrev定義はグローバルテーブル内のabbrev定義より優先される。

Variable: local-abbrev-table: このバッファーローカル変数の値は、カレントバッファーの(モード固有の)abbrevテーブルである。これは、そのようなテーブルのリストでもあり得る。

Variable: abbrev-minor-mode-table-alist: この変数の値は、(mode . abbrev-table)という形式のリストである。ここでmodeは変数の名前である。その変数が非nilにバインドされていればabbrev-tableはアクティブで、それ以外なら無視される。abbrev-tableは、abbrevテーブルのリストでもあり得る。

Variable: fundamental-mode-abbrev-table: これは、Fundamentalモードで使用される、ローカルabbrevテーブルである。言い換えると、これはFundamentalモードにあるすべてのバッファーの、ローカルabbrevテーブルである。

Variable: text-mode-abbrev-table: これは、Textモードで使用される、ローカルabbrevテーブルである。

Variable: lisp-mode-abbrev-table: これはLispモードで使用されるローカルabbrevテーブルであり、Emacs Lispモードで使用されるローカルabbrevテーブルの親テーブルである。abbrevテーブルのプロパティーを参照のこと。

36.6 abbrevプロパティー

abbrevはプロパティをもち、それらのいくつかはabbrevの働きに影響します。これらのプロパティをdefine-abbrevの引数として提供して、以下の関数で操作できます:

Function: abbrev-put abbrev prop val: abbrevのプロパティpropに値valをセットする。

Function: abbrev-get abbrev prop: abbrevのプロパティprop、そのabbrevがそのようなプロパティをもたなければnilをリターンする。

以下のプロパティには特別な意味があります:

:count: このプロパティは、そのabbrevが展開された回数を計数する。明示的にセットしなければ、define-abbrevにより0に初期化される。
:system: 非nilなら、このプロパティはシステムabbrevとして、そのabbrevをマスクする。そのようなabbrevは保存されない(ファイルへのabbrevの保存を参照)。
:enable-function: 非nilの場合、そのabbrevが使用されるべきでなければnil、それ以外ならtをリターンするような、引数なしの関数であること。
:case-fixed: 非nilなら、このプロパテぃはそのabbrevの大文字小文字には意味があり、同じパターンにcapitalizeされたテキストだけにマッチすべきことを示す。これは展開のcapitalizationを変更するコードも無効にする。

36.7 abbrevテーブルのプロパティー

abbrevと同じようにabbrevテーブルもプロパティをもち、それらのいくつかはabbrevテーブルの働きに影響を与えます。これらのプロパティをdefine-abbrev-tableの引数として提供して、それらを関数で操作できます:

Function: abbrev-table-put table prop val: abbrevテーブルtableのプロパティpropに、値valをセットする。

Function: abbrev-table-get table prop: abbrevテーブルのプロパティprop、そのabbrevテーブルがそのようなをプロパティもたなければnilをリターンする。

以下のプロパティには特別な意味があります:

:enable-function: abbrevプロパティ:enable-functionと似ているが、そのテーブル内のすべてのabbrevに適用される点が異なる。これはポイントの前のabbrevを探すことを試みる前にも使用されるので、abbrevテーブルを動的に変更することが可能である。
:case-fixed: これはabbrevプロパティ:case-fixedと似ているが、そのテーブル内のすべてのabbrevに適用される点が異なる。
:regexp: 非nilなら、このプロパティはそのテーブルを照合する前に、ポイント前のabbrev名を抽出するための方法を示す正規表現である。その正規表現がポイントの前にマッチしたときは、そのabbrev名はsubmatchの1と期待される。このプロパティがnilなら、デフォルトはbackward-wordとforward-wordを使用して、abbrevの名前を探す。このプロパティにより、単語構文以外の文字を含む名前のabbrevが使用できる。
:parents: このプロパティは、他のabbrevを継承したテーブルのリストを保持する。
:abbrev-table-modiff: このプロパティは、そのテーブルにabbrevが追加される度に増分されるカウンターを保持する。

37 Threads

Emacs Lisp provides a limited form of concurrency, called threads. All the threads in a given instance of Emacs share the same memory. Concurrency in Emacs Lisp is “mostly cooperative”, meaning that Emacs will only switch execution between threads at well-defined times. However, the Emacs thread support has been designed in a way to later allow more fine-grained concurrency, and correct programs should not rely on cooperative threading.

Currently, thread switching will occur upon explicit request via thread-yield, when waiting for keyboard input or for process output (e.g., during accept-process-output), or during blocking operations relating to threads, such as mutex locking or thread-join.

Emacs Lisp provides primitives to create and control threads, and also to create and control mutexes and condition variables, useful for thread synchronization.

While global variables are shared among all Emacs Lisp threads, local variables are not—a dynamic let binding is local. Each thread also has its own current buffer (see section カレントバッファー) and its own match data (see section マッチデータ).

Note that let bindings are treated specially by the Emacs Lisp implementation. There is no way to duplicate this unwinding and rewinding behavior other than by using let. For example, a manual implementation of let written using unwind-protect cannot arrange for variable values to be thread-specific.

In the case of lexical bindings (see section 変数のバインディングのスコーピングルール), a closure is an object like any other in Emacs Lisp, and bindings in a closure are shared by any threads invoking the closure.

37.1 Basic Thread Functions

Threads can be created and waited for. A thread cannot be exited directly, but the current thread can be exited implicitly, and other threads can be signaled.

Function: make-thread function &optional name

Create a new thread of execution which invokes function. When function returns, the thread exits.

The new thread is created with no local variable bindings in effect. The new thread’s current buffer is inherited from the current thread.

name can be supplied to give a name to the thread. The name is used for debugging and informational purposes only; it has no meaning to Emacs. If name is provided, it must be a string.

This function returns the new thread.

Function: threadp object: This function returns t if object represents an Emacs thread, nil otherwise.

Function: thread-join thread: Block until thread exits, or until the current thread is signaled. If thread has already exited, this returns immediately.

Function: thread-signal thread error-symbol data: Like signal (see section エラーをシグナルする方法), but the signal is delivered in the thread thread. If thread is the current thread, then this just calls signal immediately. Otherwise, thread will receive the signal as soon as it becomes current. If thread was blocked by a call to mutex-lock, condition-wait, or thread-join; thread-signal will unblock it.

Function: thread-yield: Yield execution to the next runnable thread.

Function: thread-name thread: Return the name of thread, as specified to make-thread.

Function: thread-alive-p thread: Return t if thread is alive, or nil if it is not. A thread is alive as long as its function is still executing.

Function: thread--blocker thread

Return the object that thread is waiting on. This function is primarily intended for debugging, and is given a “double hyphen” name to indicate that.

If thread is blocked in thread-join, this returns the thread for which it is waiting.

If thread is blocked in mutex-lock, this returns the mutex.

If thread is blocked in condition-wait, this returns the condition variable.

Otherwise, this returns nil.

Function: current-thread: Return the current thread.

Function: all-threads: Return a list of all the live thread objects. A new list is returned by each invocation.

When code run by a thread signals an error that is unhandled, the thread exits. Other threads can access the error form which caused the thread to exit using the following function.

Function: thread-last-error: This function returns the last error form recorded when a thread exited due to an error. Each thread that exits abnormally overwrites the form stored by the previous thread’s error with a new value, so only the last one can be accessed.

37.2 Mutexes

A mutex is an exclusive lock. At any moment, zero or one threads may own a mutex. If a thread attempts to acquire a mutex, and the mutex is already owned by some other thread, then the acquiring thread will block until the mutex becomes available.

Emacs Lisp mutexes are of a type called recursive, which means that a thread can re-acquire a mutex it owns any number of times. A mutex keeps a count of how many times it has been acquired, and each acquisition of a mutex must be paired with a release. The last release by a thread of a mutex reverts it to the unowned state, potentially allowing another thread to acquire the mutex.

Function: mutexp object: This function returns t if object represents an Emacs mutex, nil otherwise.

Function: make-mutex &optional name: Create a new mutex and return it. If name is specified, it is a name given to the mutex. It must be a string. The name is for debugging purposes only; it has no meaning to Emacs.

Function: mutex-name mutex: Return the name of mutex, as specified to make-mutex.

Function: mutex-lock mutex: This will block until this thread acquires mutex, or until this thread is signaled using thread-signal. If mutex is already owned by this thread, this simply returns.

Function: mutex-unlock mutex: Release mutex. If mutex is not owned by this thread, this will signal an error.

Macro: with-mutex mutex body…: This macro is the simplest and safest way to evaluate forms while holding a mutex. It acquires mutex, invokes body, and then releases mutex. It returns the result of body.

37.3 Condition Variables

A condition variable is a way for a thread to block until some event occurs. A thread can wait on a condition variable, to be woken up when some other thread notifies the condition.

A condition variable is associated with a mutex and, conceptually, with some condition. For proper operation, the mutex must be acquired, and then a waiting thread must loop, testing the condition and waiting on the condition variable. For example:

(with-mutex mutex
  (while (not global-variable)
    (condition-wait cond-var)))

The mutex ensures atomicity, and the loop is for robustness—there may be spurious notifications.

Similarly, the mutex must be held before notifying the condition. The typical, and best, approach is to acquire the mutex, make the changes associated with this condition, and then notify it:

(with-mutex mutex
  (setq global-variable (some-computation))
  (condition-notify cond-var))

Function: make-condition-variable mutex &optional name: Make a new condition variable associated with mutex. If name is specified, it is a name given to the condition variable. It must be a string. The name is for debugging purposes only; it has no meaning to Emacs.

Function: condition-variable-p object: This function returns t if object represents a condition variable, nil otherwise.

Function: condition-wait cond

Wait for another thread to notify cond, a condition variable. This function will block until the condition is notified, or until a signal is delivered to this thread using thread-signal.

It is an error to call condition-wait without holding the condition’s associated mutex.

condition-wait releases the associated mutex while waiting. This allows other threads to acquire the mutex in order to notify the condition.

Function: condition-notify cond &optional all

Notify cond. The mutex with cond must be held before calling this. Ordinarily a single waiting thread is woken by condition-notify; but if all is not nil, then all threads waiting on cond are notified.

condition-notify releases the associated mutex while waiting. This allows other threads to acquire the mutex in order to wait on the condition.

Function: condition-name cond: Return the name of cond, as passed to make-condition-variable.

Function: condition-mutex cond: Return the mutex associated with cond. Note that the associated mutex cannot be changed.

38 プロセス

オペレーティングシステムの用語では、プロセス(process)とはプログラムを実行できるスペースのことです。Emacsはプロセス内で実行されます。Emacs Lispプログラムは、別のプログラムをそれら自身のプロセス内で呼び出すことができます。これらは、親プロセス(parent process)であるEmacsプロセスのサブプロセス(subprocesses)、または子プロセス(child processes)と呼ばれます。

Emacsのサブプロセスは同期(synchronous)、または非同期(asynchronous)であり、それはそれらが作成された方法に依存します。同期サブプロセスを作成した際、Lispプログラムは実行を継続する前に、そのサブプロセスの終了を待機します。非同期サブプロセスを作成したときは、それをLispプログラムと並行して実行できます。この種のサブプロセスは、EmacsではLispオブジェクととして表現され、そのオブジェクトも“プロセス”と呼ばれています。Lispプログラムはサブプロセスとのやり取りや、サブプロセスの制御のために、このオブジェクトを使用できます。たとえばシグナル送信、ステータス情報の取得、プロセス出力の受信や、プロセスへ入力を送信することができます。

In addition to processes that run programs, Lisp programs can open connections of several types to devices or processes running on the same machine or on other machines. The supported connection types are: TCP and UDP network connections, serial port connections, and pipe connections. Each such connection is also represented by a process object.

Function: processp object: This function returns t if object represents an Emacs process object, nil otherwise. The process object can represent a subprocess running a program or a connection of any supported type.

カレントEmacsセッションのサブプロセスに加えて、そのマシン上で実行中の他のプロセスにアクセスすることもできます。別のプセスへのアクセスを参照してください。

38.1 サブプロセスを作成する関数		サブプロセスを開始する関数。
38.2 shell引数		shellに渡すために引数をクォートする。
38.3 同期プロセスの作成		同期サブプロセス使用の詳細。
38.4 非同期プロセスの作成		非同期サブプロセスの起動。
38.5 プロセスの削除		非同期サブプロセスの削除。
38.6 プロセスの情報		実行状態および他の属性へのアクセス。
38.7 プロセスへの入力の送信		非同期サブプロセスへの入力の送信。
38.8 プロセスへのシグナルの送信		非同期サブプロセスの停止、継続、割り込み。
38.9 プロセスからの出力の受信		非同期サブプロセスからの出力の収集。
38.10 センチネル: プロセス状態の変更の検知		プロセスの実行状態変更時に実行されるセンチネル。
38.11 exit前の問い合わせ		exitによりプロセスがkillされる場合に問い合わせるかどうか。
38.12 別のプセスへのアクセス		そのシステム上で実行中の別プロセスへのアクセス。
38.13 トランザクションキュー		サブプロセスとのトランザクションベースのコミュニケション。
38.14 ネットワーク接続		ネットワーク接続のopen。
38.15 ネットワークサーバー		Emacsによるネット接続のacceptを可能にするネットワークサーバー。
38.16 データグラム		UDPネットワーク接続。
38.17 低レベルのネットワークアクセス		接続およびサーバーを作成するための、より低レベルだがより汎用的な関数。
38.18 その他のネットワーク機能		ネット接続用の追加の関連関数。
38.19 シリアルポートとの対話		シリアルポートでのやり取り。
38.20 バイト配列のpackとunpack		bindatを使用したバイナリーデータのpackとunpack。

38.1 サブプロセスを作成する関数

There are three primitives that create a new subprocess in which to run a program. One of them, make-process, creates an asynchronous process and returns a process object (see section 非同期プロセスの作成). The other two, call-process and call-process-region, create a synchronous process and do not return a process object (see section 同期プロセスの作成). There are various higher-level functions that make use of these primitives to run particular types of process.

同期プロセスと非同期プロセスについては、以降のセクションで説明します。この3つの関数はすべて類似した様式で呼び出されるので、ここでそれらに共通の引数について説明します。

In all cases, the functions specify the program to be run. An error is signaled if the file is not found or cannot be executed. If the file name is relative, the variable exec-path contains a list of directories to search. Emacs initializes exec-path when it starts up, based on the value of the environment variable PATH. The standard file name constructs, ‘~’, ‘.’, and ‘..’, are interpreted as usual in exec-path, but environment variable substitutions (‘$HOME’, etc.) are not recognized; use substitute-in-file-name to perform them (see section ファイル名を展開する関数). nil in this list refers to default-directory.

プログラムの実行では、指定された名前にサフィックスの追加を試みることもできます:

User Option: exec-suffixes: この変数は、指定されたプログラムファイル名への追加を試みるための、サフィックス(文字列)のリストである。指定されたとおりの名前を試みたいなら、このリストに""を含めること。デフォルト値はシステムに依存する。

Please note: The argument program contains only the name of the program file; it may not contain any command-line arguments. You must use a separate argument, args, to provide those, as described below.

Each of the subprocess-creating functions has a buffer-or-name argument that specifies where the output from the program will go. It should be a buffer or a buffer name; if it is a buffer name, that will create the buffer if it does not already exist. It can also be nil, which says to discard the output, unless a custom filter function handles it. (See section プロセスのフィルター関数, and Lispオブジェクトの読み取りとプリント.) Normally, you should avoid having multiple processes send output to the same buffer because their output would be intermixed randomly. For synchronous processes, you can send the output to a file instead of a buffer (and the corresponding argument is therefore more appropriately called destination). By default, both standard output and standard error streams go to the same destination, but all the 3 primitives allow optionally to direct the standard error stream to a different destination.

All three of the subprocess-creating functions allow to specify command-line arguments for the process to run. For call-process and call-process-region, these come in the form of a &rest argument, args. For make-process, both the program to run and its command-line arguments are specified as a list of strings. The command-line arguments must all be strings, and they are supplied to the program as separate argument strings. Wildcard characters and other shell constructs have no special meanings in these strings, since the strings are passed directly to the specified program.

サブプロセスはその環境をEmacsから継承しますが、process-environmentでそれをオーバーラードするよう指定することができます。オペレーティングシステムの環境を参照してください。サブプロセスは自身のカレントディレクトリーを、default-directoryの値から取得します。

Variable: exec-directory: この変数の値は、GNU Emacsとともに配布され、Emacsにより呼び出されることを意図したプログラムを含むディレクトリーの名前(文字列)である。プログラムmovemailはそのようなプログラムの例であり、Rmailはinboxから新しいメールを読み込むためにこのプログラムを使用する。

User Option: exec-path

The value of this variable is a list of directories to search for programs to run in subprocesses. Each element is either the name of a directory (i.e., a string), or nil, which stands for the default directory (which is the value of default-directory). See section executable-find, for the details of this search.

exec-pathの値は、program引数が絶対ファイル名でないとき、call-processおよびstart-processにより使用される。

一般的には、exec-pathを直接変更するべきではない。かわりにEmacs起動前に、環境変数PATHが適切にセットされているか確認すること。PATHとは独立にexec-pathの変更を試みると、混乱した結果へと導かれ得る。

38.2 shell引数

Lispプログラムがshellを実行して、ユーザーが指定したファイル名を含むコマンドを与える必要がある場合が時折あります。これらのプログラムは、任意の有効なファイル名をサポート可能であるはずです。しかしshellは特定の文字を特別に扱い、それらの文字がファイル名に含まれていると、shellを混乱させるでしょう。これらの文字を処理するためには、関数shell-quote-argumentを使用します。

Function: shell-quote-argument argument

この関数は、実際のコンテンツがargumentであるような引数を表す文字列を、shellの構文でリターンする。リターン値をshellコマンドに結合して、実行のためにそれをshellに渡すことにより、信頼性をもって機能するはずである。

Precisely what this function does depends on your operating system. The function is designed to work with the syntax of your system’s standard shell; if you use an unusual shell, you will need to redefine this function. See section Security Considerations.

;; この例はGNUおよびUnixシステムでの挙動を示す
(shell-quote-argument "foo > bar")
     ⇒ "foo\\ \\>\\ bar"

;; この例はMS-DOSおよびMS-Windowsでの挙動を示す
(shell-quote-argument "foo > bar")
     ⇒ "\"foo > bar\""

以下はshell-quote-argumentを使用して、shellコマンドを構築する例である:

(concat "diff -u "
        (shell-quote-argument oldfile)
        " "
        (shell-quote-argument newfile))

The following two functions are useful for combining a list of individual command-line argument strings into a single string, and taking a string apart into a list of individual command-line arguments. These functions are mainly intended for converting user input in the minibuffer, a Lisp string, into a list of string arguments to be passed to make-process, call-process or start-process, or for converting such lists of arguments into a single Lisp string to be presented in the minibuffer or echo area. Note that if a shell is involved (e.g., if using call-process-shell-command), arguments should still be protected by shell-quote-argument; combine-and-quote-strings is not intended to protect special characters from shell evaluation.

Function: split-string-and-unquote string &optional separators

この関数はsplit-string(see section 文字列の作成を参照)が行うように、正規表現separatorsにたいするマッチで、stringを部分文字列に分割する。さらに加えて、その部分文字列からクォートを削除する。それから部分文字列のリストを作成して、それをリターンする。

separatorsが省略、またはnilの場合のデフォルトは"\\s-+"で、これは空白文字構文(構文クラスのテーブルを参照)をもつ1つ以上の文字にマッチする正規表現である。

この関数は、2つのタイプのクォートをサポートする。1つは文字列全体をダブルクォートで囲う"…"のようなクォートで、もう1つはバックスラッシュ‘\’によるエスケープで文字を個別にクォートするタイプである。後者はLisp文字列内でも使用されるので、この関数はそれらも同様に扱うことができる。

Function: combine-and-quote-strings list-of-strings &optional separator

この関数は、list-of-stringsの各文字を必要に応じてクォートして、単一の文字列に結合する。これはさらに各文字ペアーの間に、separator文字列も挿入する。separatorが省略またはnilの場合のデフォルトは" "。リターン値は、その結果の文字列である。

list-of-strings内のクォートを要する文字列には、部分文字列としてseparatorを含むものが該当する。文字列のクォートは、それをダブルクォートで"…"のように囲う。もっとも単純な例では、個別のコマンドライン引数からコマンドをコンス(cons)する場合は、埋め込まれたブランクを含む文字列はそれぞれクォートされるだろう。

38.3 同期プロセスの作成

同期プロセス(synchronous process)の作成後、Emacsは継続の前にそのプロセスが終了するのを待機します。GNUやUnix¹⁸でのDiredの起動が、この例です。プロセスは同期的なので、Emacsがそれにたいして何か行おうと試みる前に、ディレクトリーのリスト全体がバッファーに到着します。

同期サブプロセス終了をEmacsが待機する間、ユーザーはC-gをタイプすることによりquitができます。最初のはC-gはSIGINTシグナルにより、サブプロセスのkillを試みます。しかしこれはquitする前に、実際にそのサブプロセスが終了されるまで待機します。その間にユーザーがさらにC-gをタイプすると、それはSIGKILLで即座にサブプロセスをkillしてquitします(別プロセスのkillが機能しないMS-DOSを除く)。quitを参照してください。

同期サブプロセス関数は、プロセスがどのように終了したかの識別をリターンします。

同期サブプロセスからの出力は、ファイルからのテキスト読み込みと同じように、一般的にはコーディングシステムを使用してデコードされます。call-process-regionによりサブプロセスに送信された入力は、ファイルへのテキスト書き込みと同じように、コーディングシステムを使用してエンコードされます。コーディングシステムを参照してください。

Function: call-process program &optional infile destination display &rest args

この関数はprogramを呼び出して、それが完了するまで待機する。

The current working directory of the subprocess is set to the current buffer’s value of default-directory if that is local (as determined by unhandled-file-name-directory), or "~" otherwise. If you want to run a process in a remote directory use process-file.

新たなプロセスの標準入力は、infileが非nilならファイルnilから、それ以外ならnullデバイスからとなる。引数destinationは、プロセスの出力をどこに送るかを指定する。以下は可能な値である:

バッファー

そのバッファーの、ポイントの前に出力を挿入する。これにはプロセスの、標準出力ストリームと標準エラーストリームの両方が含まれる。

a buffer name (a string)

その名前のバッファーの、ポイントの前に出力を挿入する。

t

カレントバッファーの、ポイントの前に出力を挿入する。

nil

出力を破棄する。

0

出力を破棄して、サブプロセス完了を待機することなく、即座にnilをリターンする。

この場合、プロセスはEmacsと並列に実行可能なので、真に同期的ではない。しかしこの関数リターン後は、本質的にはすみやかにEmacsがサブプロセスを終了するという点から、これを同期的と考えることができる。

MS-DOSは非同期サブプロセスをサポートせず、このオプションは機能しない。

(:file file-name)

指定されたファイルに出力を送信し、ファイルが既に存在すれば上書きする。

(real-destination error-destination)

標準出力ストリームを、標準エラーストリームと分けて保つ。通常の出力はreal-destinationの指定にしたがって扱い、エラー出力はerror-destinationにしたがって処分する。error-destinationがnilならエラー出力の破棄、tなら通常の出力と混合することを意味し、文字列ならそれはエラー出力をリダイレクトするファイルの名前である。

You can’t directly specify a buffer to put the error output in; that is too difficult to implement. But you can achieve this result by sending the error output to a temporary file and then inserting the file into a buffer when the subprocess finishes.

displayが非nilなら、call-processは出力の挿入にしたがって、バッファーを再表示する(しかし出力のデコードに選択されたコーディングシステムが、実データからエンコーディングを推論することを意味するundecidedの場合は、非ASCIIに一度遭遇すると再表示が継続不能になることがある。これを修正するのが困難な根本的理由が存在する。プロセスからの出力の受信を参照されたい)。

それ以外なら関数call-processは再表示を行わず、通常のイベントに由来するEmacsの再表示時だけ、スクリーン上で結果が可視になります。

The remaining arguments, args, are strings that specify command line arguments for the program. Each string is passed to program as a separate argument.

The value returned by call-process (unless you told it not to wait) indicates the reason for process termination. A number gives the exit status of the subprocess; 0 means success, and any other value means failure. If the process terminated with a signal, call-process returns a string describing the signal. If you told call-process not to wait, it returns nil.

以下の例では、カレントバッファーは‘foo’です。

(call-process "pwd" nil t)
     ⇒ 0

---------- Buffer: foo ----------
/home/lewis/manual
---------- Buffer: foo ----------

(call-process "grep" nil "bar" nil "lewis" "/etc/passwd")
     ⇒ 0

---------- Buffer: bar ----------
lewis:x:1001:1001:Bil Lewis,,,,:/home/lewis:/bin/bash

---------- Buffer: bar ----------

以下はcall-processの使用法の例で、このような使用例はinsert-directory関数の定義内で見ることができます:

(call-process insert-directory-program nil t nil switches
              (if full-directory-p
                  (concat (file-name-as-directory file) ".")
                file))

Function: process-file program &optional infile buffer display &rest args

この関数は、別プロセス内でファイルを同期的に処理する。これはcall-processと似ているが、サブプロセスのカレントワーキングディレクトリーを指定する、変数default-directoryの値にもとづく、ファイルハンドラーを呼び出すかもしれない。

引数はcall-processの場合とほとんど同様の方法で処理されるが、以下の違いがある:

引数infile、buffer、displayの組み合わせと形式.をサポートしないファイルハンドラーがあるかもしれない。たとえば実際に渡された値とは無関係に、displayがnilであるかのように振る舞うファイルハンドラーがいくつかある。他の例としては、buffer引数で標準出力とエラー出力を分離するのをサポートしないかもしれないファイルハンドラーがいくつか存在する。

ファイルハンドラーが呼び出されると、1つ目の引数programにもとづき、実行するプログラムを決定する。たとえばリモートファイルにたいするハンドラーが呼び出されたと考えてみよ。その.場合、プログラムの検索に使用されるパスは、exec-pathとは異なるかもしれない。

2つ目の引数infileは、ファイルハンドラーを呼び出すかもしれない。そのファイルハンドラーは、process-file関数自身にたいして選択されたハンドラーと異なり得る(たとえばdefault-directoryがリモートホスト上にあり、infileは別のリモートホスト上の場合があり得る。もしくはdefault-directoryは普通だが、infileはリモートホスト上にあるかもしれない).

bufferが(real-destination error-destination)という形式のリストで、error-destinationがファイルの名前なら、infileと同じ注意が適用される。

残りの引数(args)は、そのままプロセスに渡される。Emacsは、args内で与えられたファイル名の処理に関与しない。混乱を避けるためには、args内で絶対ファイル名を使用しないのが最善であり、default-directoryからの相対ファイル名ですべてのファイルを指定するほうがよいだろう。関数file-relative-nameは、そのような相対ファイル名の構築に有用である。

Variable: process-file-side-effects

この変数は、process-file呼び出しがリモートファイルを変更するかどうかを示す。

この変数はデフォルトでは常に、process-file呼び出しがリモートホスト上の、任意のファイルを潜在的に変更し得ることを意味するtにセットされる。nilにセットされた際は、リモートファイル属性のキャッシュにしたがうことにより、ファイルハンドラーの挙動を最適化できる可能性がある。

この変数は決してsetqではなく、常にletバインディングによってのみ変更されるべきである。

Function: call-process-region start end program &optional delete destination display &rest args

この関数はstartからendのテキストを、実行中のプロセスprogramに、標準入力として送信する。これはdeleteが非nilなら、送信したテキストを削除する。これは出力をカレントバッファーの入力箇所に挿入するために、destinationをtに指定している際に有用である。

引数destinationとdisplayは、サブロセスからの出力にたいして何を行うか、および出力の到着にともない表示を更新するかどうかを制御する。詳細は上述の、call-processの説明を参照されたい。destinationが整数の0なら、call-process-regionは出力を破棄して、サブプロセス完了を待機せずに、即座にnilをリターンする(これは非同期サブプロセスがサポートされる場合、つまりMS-DOS以外でのみ機能する)。

残りの引数argsは、そのプログラムにたいしてコマンドライン引数を指定する文字列です。

call-process-regionのリターン値は、call-processの場合と同じである。待機せずにリターンするよう指示した場合はnil、数字か文字列ならそれはサブプロセスが終了した方法を表す。

以下の例では、バッファー‘foo’内の最初の5文字(単語‘input’)を標準入力として、call-process-regionを使用してcatユーティリティを実行する。catは自身の標準入力を、標準出力へコピーする。引数destinationがtなので、その出力はカレントバッファーに挿入される。

---------- Buffer: foo ----------
input∗
---------- Buffer: foo ----------

(call-process-region 1 6 "cat" nil t)
     ⇒ 0

---------- Buffer: foo ----------
inputinput∗
---------- Buffer: foo ----------

For example, the shell-command-on-region command uses call-shell-region in a manner similar to this:

(call-shell-region
 start end
 command              ; shell command
 nil                  ; do not delete region
 buffer)              ; send output to buffer

Function: call-process-shell-command command &optional infile destination display: This function executes the shell command command synchronously. The other arguments are handled as in call-process. An old calling convention allowed passing any number of additional arguments after display, which were concatenated to command; this is still supported, but strongly discouraged.

Function: process-file-shell-command command &optional infile destination display: This function is like call-process-shell-command, but uses process-file internally. Depending on default-directory, command can be executed also on remote hosts. An old calling convention allowed passing any number of additional arguments after display, which were concatenated to command; this is still supported, but strongly discouraged.

Function: call-shell-region start end command &optional delete destination: This function sends the text from start to end as standard input to an inferior shell running command. This function is similar than call-process-region, with process being a shell. The arguments delete, destination and the return value are like in call-process-region. Note that this function doesn’t accept additional arguments.

Function: shell-command-to-string command: この関数はshellコマンドとしてcommand(文字列)を実行して、そのコマンドの出力を文字列としてリターンする。

Function: process-lines program &rest args

この関数はprogramを実行して完了を待機し、出力を文字列のリストとしてリターンする。リスト内の各文字列は、プログラムのテキスト出力の1つの行を保持する。各行のEOL文字(行末文字)は取り除かれる。programの後の引数argsは、そのプログラム実行に際し、コマンドライン引数を指定する文字列である。

programが非0のexitステータスでexitした場合、この関数はエラーをシグナルする。

この関数はcall-processを呼び出すことにより機能し、プログラムの出力はcall-processの場合と同じ方法でデコードされる。

38.4 非同期プロセスの作成

このセクションでは、非同期プロセス(asynchronous process)を作成する方法について説明します。非同期プロセスは作成後、Emacsと並列して実行され、Emacsは以降のセクション(プロセスへの入力の送信およびプロセスからの出力の受信を参照)で説明する関数を使用してプロセスとコミュニケーションができます。プロセスコミュニケーションは、部分的に非同期なだけであることに注意してください。Emacsは特定の関数を呼び出したときだけプロセスにデータを送信でき、Emacsは入力の待機中または一定の遅延時間の後にのみ、プロセスのデータを受け取ることができます。

An asynchronous process is controlled either via a pty (pseudo-terminal) or a pipe. The choice of pty or pipe is made when creating the process, by default based on the value of the variable process-connection-type (see below). If available, ptys are usually preferable for processes visible to the user, as in Shell mode, because they allow for job control (C-c, C-z, etc.) between the process and its children, and because interactive programs treat ptys as terminal devices, whereas pipes don’t support these features. However, for subprocesses used by Lisp programs for internal purposes, it is often better to use a pipe, because pipes are more efficient, and because they are immune to stray character injections that ptys introduce for large (around 500 byte) messages. Also, the total number of ptys is limited on many systems and it is good not to waste them.

Function: make-process &rest args

This function is the basic low-level primitive for starting asynchronous subprocesses. It returns a process object representing the subprocess. Compared to the more high-level start-process, described below, it takes keyword arguments, is more flexible, and allows to specify process filters and sentinels in a single call.

The arguments args are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value nil. Here are the meaningful keywords:

:name name

Use the string name as the process name; if a process with this name already exists, then name is modified (by appending ‘<1>’, etc.) to be unique.

:buffer buffer

Use buffer as the process buffer. If the value is nil, the subprocess is not associated with any buffer.

:command command

Use command as the command line of the process. The value should be a list starting with the program’s executable file name, followed by strings to give to the program as its arguments. If the first element of the list is nil, Emacs opens a new pseudoterminal (pty) and associates its input and output with buffer, without actually running any program; the rest of the list elements are ignored in that case.

:coding coding

If coding is a symbol, it specifies the coding system to be used for both reading and writing of data from and to the connection. If coding is a cons cell (decoding . encoding), then decoding will be used for reading and encoding for writing. The coding system used for encoding the data written to the program is also used for encoding the command-line arguments (but not the program itself, whose file name is encoded as any other file name; see section file-name-coding-system).

If coding is nil, the default rules for finding the coding system will apply. See section デフォルトのコーディングシステム.

:connection-type type

Initialize the type of device used to communicate with the subprocess. Possible values are pty to use a pty, pipe to use a pipe, or nil to use the default derived from the value of the process-connection-type variable. This parameter and the value of process-connection-type are ignored if a non-nil value is specified for the :stderr parameter; in that case, the type will always be pipe.

:noquery query-flag

プロセスqueryフラグをquery-flagに初期化する。exit前の問い合わせを参照のこと。

:stop stopped

If stopped is non-nil, start the process in the stopped state.

:filter filter

Initialize the process filter to filter. If not specified, a default filter will be provided, which can be overridden later. See section プロセスのフィルター関数.

:sentinel sentinel

Initialize the process sentinel to sentinel. If not specified, a default sentinel will be used, which can be overridden later. See section センチネル: プロセス状態の変更の検知.

:stderr stderr

Associate stderr with the standard error of the process. A non-nil value should be either a buffer or a pipe process created with make-pipe-process, described below.

実際の接続情報で修正されたオリジナルの引数リストは、process-contactを通じて利用できる。

The current working directory of the subprocess is set to the current buffer’s value of default-directory if that is local (as determined by ‘unhandled-file-name-directory’), or "~" otherwise. If you want to run a process in a remote directory use start-file-process.

Function: make-pipe-process &rest args

This function creates a bidirectional pipe which can be attached to a child process. This is useful with the :stderr keyword of make-process. The function returns a process object.

The arguments args are a list of keyword/argument pairs. Omitting a keyword is always equivalent to specifying it with value nil.

Here are the meaningful keywords:

:name name

Use the string name as the process name. As with make-process, it is modified if necessary to make it unique.

:buffer buffer

プロセスバッファーとしてbufferを使用する。

:coding coding

If coding is nil, the default rules for finding the coding system will apply. See section デフォルトのコーディングシステム.

:noquery query-flag

プロセスqueryフラグをquery-flagに初期化する。exit前の問い合わせを参照のこと。

:stop stopped

If stopped is non-nil, start the process in the stopped state. In the stopped state, a pipe process does not accept incoming data, but you can send outgoing data. The stopped state is set by stop-process and cleared by continue-process (see section プロセスへのシグナルの送信).

:filter filter

Initialize the process filter to filter. If not specified, a default filter will be provided, which can be changed later. See section プロセスのフィルター関数.

:sentinel sentinel

Initialize the process sentinel to sentinel. If not specified, a default sentinel will be used, which can be changed later. See section センチネル: プロセス状態の変更の検知.

実際の接続情報で修正されたオリジナルの引数リストは、process-contactを通じて利用できる。

Function: start-process name buffer-or-name program &rest args

This function is a higher-level wrapper around make-process, exposing an interface that is similar to call-process. It creates a new asynchronous subprocess and starts the specified program running in it. It returns a process object that stands for the new subprocess in Lisp. The argument name specifies the name for the process object; as with make-process, it is modified if necessary to make it unique. The buffer buffer-or-name is the buffer to associate with the process.

programがnilなら、Emacsは疑似端末(pty)を新たにオープンして、サブプロセスを新たに作成することなく、ptyの入力と出力をbuffer-or-nameに関連付ける。この場合、残りの引数argsは無視される。

The rest of args are strings that specify command line arguments for the subprocess.

以下の例では、1つ目のプロセスが開始して、100秒間実行(というよりはsleep)される。その間に2つ目のプロセスが開始して、一意性を保つために‘my-process<1>’という名前が与えられる。これは1つ目のプロセスが終了する前に、バッファー‘foo’の最後にディレクトリーのリストを挿入する。その後、2つ目のプロセスは終了して、その旨のメッセージがバッファーに挿入される。さらに遅れて1つ目のプロセスが終了して、バッファーに別のメッセージが挿入される。

(start-process "my-process" "foo" "sleep" "100")
     ⇒ #<process my-process>

(start-process "my-process" "foo" "ls" "-l" "/bin")
     ⇒ #<process my-process<1>>

---------- Buffer: foo ----------
total 8336
-rwxr-xr-x 1 root root 971384 Mar 30 10:14 bash
-rwxr-xr-x 1 root root 146920 Jul  5  2011 bsd-csh
…
-rwxr-xr-x 1 root root 696880 Feb 28 15:55 zsh4

Process my-process<1> finished

Process my-process finished
---------- Buffer: foo ----------

Function: start-file-process name buffer-or-name program &rest args

start-processと同様、この関数は非同期サブプロセスを開始して、その内部でprogramを実行して、そのプロセスオブジェクトをリターンする。

The difference from start-process is that this function may invoke a file handler based on the value of default-directory. This handler ought to run program, perhaps on the local host, perhaps on a remote host that corresponds to default-directory. In the latter case, the local part of default-directory becomes the working directory of the process.

This function does not try to invoke file name handlers for program or for the rest of args.

そのファイルハンドラーの実装によっては、リターン結果のプロセスオブジェクトにprocess-filterまたはprocess-sentinelを適用することができないかもしれない。プロセスのフィルター関数およびセンチネル: プロセス状態の変更の検知を参照されたい。

いくつかのファイルハンドラーはstart-file-processをサポートしないかもしれない(たとえばange-ftp-hook-function関数)。そのような場合、この関数は何も行わずにnilをリターンする。

Function: start-process-shell-command name buffer-or-name command

This function is like start-process, except that it uses a shell to execute the specified command. The argument command is a shell command string. The variable shell-file-name specifies which shell to use.

The point of running a program through the shell, rather than directly with make-process or start-process, is so that you can employ shell features such as wildcards in the arguments. It follows that if you include any arbitrary user-specified arguments in the command, you should quote them with shell-quote-argument first, so that any special shell characters do not have their special shell meanings. See section shell引数. Of course, when executing commands based on user input you should also consider the security implications.

Function: start-file-process-shell-command name buffer-or-name command: この関数はstart-process-shell-commandと似ているが、内部的にstart-file-processを使用する点が異なる。これにより、default-directoryに応じてリモートホスト上でも、commandを実行できる。

Variable: process-connection-type

この変数は、非同期サブプロセスと対話するために使用する、デバイスタイプを制御する。これが非nilの場合、利用可能ならpty、それ以外ならpipeが使用される。

The value of process-connection-type takes effect when make-process or start-process is called. So you can specify how to communicate with one subprocess by binding the variable around the call to these functions.

Note that the value of this variable is ignored when make-process is called with a non-nil value of the :stderr parameter; in that case, Emacs will communicate with the process using pipes.

(let ((process-connection-type nil))  ; pipeを使用
  (start-process …))

与えられたサブプロセスが実際にはpipeとptyのどちらを取得したかを判断するには、関数process-tty-nameを使用する(プロセスの情報を参照)。

38.5 プロセスの削除

プロセス削除(deleting a process)とは、Emacsをサブプロセスから即座に切断することです。プロセスは終了後に自動的に削除されますが、即座に削除される必要はありません。任意のタイミングで、明示的にプロセスを削除できます。終了したプロセスが自動的に削除される前に明示的に削除しても、それに害はありません。実行中のプロセスの削除は、プロセス(もしあれば子プロセスにも)を終了するためにシグナルを送信して、プロセスセンチネルを呼び出します。センチネル: プロセス状態の変更の検知を参照してください。

プロセスが削除される際、そのプロセスオブジェクト自体は、それを参照する別のLispオブジェクトが存在する限り、継続し続けます。プロセスオブジェクトに作用するすべてのLispプリミティブはプロセスの削除を受け入れますが、I/Oを行ったりシグナルを送信するプリミティブは、エラーを報告するでしょう。プロセスマークは、通常はプロセスからの出力がバッファーに挿入される箇所である、以前と同じ箇所をポイントし続けます。

User Option: delete-exited-processes: この変数は、(exit呼び出しやシグナルにより)終了したプロセスの、自動的な削除を制御する。これがnilなら、ユーザーがlist-processesを実行するまでプロセスは存在し続け、それ以外ならexit後に即座に削除される。

Function: delete-process process

This function deletes a process, killing it with a SIGKILL signal if the process was running a program. The argument may be a process, the name of a process, a buffer, or the name of a buffer. (A buffer or buffer-name stands for the process that get-buffer-process returns.) Calling delete-process on a running process terminates it, updates the process status, and runs the sentinel immediately. If the process has already terminated, calling delete-process has no effect on its status, or on the running of its sentinel (which will happen sooner or later).

If the process object represents a network, serial, or pipe connection, its status changes to closed; otherwise, it changes to signal, unless the process already exited. See section process-status.

(delete-process "*shell*")
     ⇒ nil

38.6 プロセスの情報

プロセスの状態に関する情報をリターンする関数がいくつかあり。

Command: list-processes &optional query-only buffer

このコマンドは、すべての生きたプロセスのリストを表示する。加えてこれは最後に、状態が‘Exited’か‘Signaled’だったすべてのプロセスを削除する。このコマンドはnilをリターンする。

プロセスは、メジャーモードがProcess Menuモードであるような、*Process List*という名前(オプション引数bufferで他の名前を指定していない場合)のバッファーに表示される。

query-onlyが非nilなら、queryフラグが非nilのプロセスだけをリストする。exit前の問い合わせを参照のこと。

Function: process-list

この関数は、削除されていないすべてのプロセスのリストをリターンする。

(process-list)
     ⇒ (#<process display-time> #<process shell>)

Function: get-process name

This function returns the process named name (a string), or nil if there is none. The argument name can also be a process object, in which case it is returned.

(get-process "shell")
     ⇒ #<process shell>

Function: process-command process

This function returns the command that was executed to start process. This is a list of strings, the first string being the program executed and the rest of the strings being the arguments that were given to the program. For a network, serial, or pipe connection, this is either nil, which means the process is running or t (process is stopped).

(process-command (get-process "shell"))
     ⇒ ("bash" "-i")

Function: process-contact process &optional key

This function returns information about how a network, a serial, or a pipe connection was set up. When key is nil, it returns (hostname service) for a network connection, (port speed) for a serial connection, and t for a pipe connection. For an ordinary child process, this function always returns t when called with a nil key.

If key is t, the value is the complete status information for the connection, server, serial port, or pipe; that is, the list of keywords and values specified in make-network-process, make-serial-process, or make-pipe-process, except that some of the values represent the current status instead of what you specified.

ネットワークプロセスにたいしては、その値が含まれる(完全なリストについては、make-network-processを参照されたい)。

:buffer: 値にはプロセスのバッファーが割り当てられる。
:filter: The associated value is the process filter function. See section プロセスのフィルター関数.
:sentinel: The associated value is the process sentinel function. See section センチネル: プロセス状態の変更の検知.
:remote: 接続にたいしては、内部的なフォーマットによる、リモートピアーのアドレス。
:local: 内部的なフォーマットによる、ローカルアドレス。
:service: サーバーにおいては、serviceにtを指定した場合、この値は実際のポート番号。

make-network-process内で明示的に指定されていなくても、:localと:remoteは値に含まれる。

For a serial connection, see make-serial-process and serial-process-configure for the list of keys. For a pipe connection, see make-pipe-process for the list of keys.

keyがキーワードなら、この関数はそのキーワードに対応する値をリターンする。

Function: process-id process: This function returns the PID of process. This is an integral number that distinguishes the process process from all other processes running on the same computer at the current time. The PID of a process is chosen by the operating system kernel when the process is started and remains constant as long as the process exists. For network, serial, and pipe connections, this function returns nil.

Function: process-name process: この関数はprocessの名前を、文字列としてリターンする。

Function: process-status process-name

この関数はprocess-nameの状態を、文字列としてリターンする。引数process-nameはプロセス、バッファー、またはプロセス名(文字列)かもしれない。

実際のサブプセスにたいして可能な値は:

run: 実行中のプロセス。
stop: 停止しているが継続可能なプロセス。
exit: exitしたプロセス。
signal: 致命的なシグナルを受信したプロセス。
open: for a network, serial, or pipe connection that is open.
closed: for a network, serial, or pipe connection that is closed. Once a connection is closed, you cannot reopen it, though you might be able to open a new connection to the same place.
connect: 完了を待つ非ブロッキング接続。
failed: 完了に失敗した非ブロッキング接続。
listen: listen中のネットワークサーバー。
nil: process-nameが既存のプロセス名でない場合。

(process-status (get-buffer "*shell*"))
     ⇒ run

For a network, serial, or pipe connection, process-status returns one of the symbols open, stop, or closed. The latter means that the other side closed the connection, or Emacs did delete-process. The value stop means that stop-process was called on the connection.

Function: process-live-p process: この関数は、processがアクティブなら、非nilをリターンする。状態がrun、open、listen、connect、stopのプロセスはアクティブとみなされる。

Function: process-type process: This function returns the symbol network for a network connection or server, serial for a serial port connection, pipe for a pipe connection, or real for a subprocess created for running a program.

Function: process-exit-status process: This function returns the exit status of process or the signal number that killed it. (Use the result of process-status to determine which of those it is.) If process has not yet terminated, the value is 0. For network, serial, and pipe connections that are already closed, the value is either 0 or 256, depending on whether the connection was closed normally or abnormally.

Function: process-tty-name process: This function returns the terminal name that process is using for its communication with Emacs—or nil if it is using pipes instead of a pty (see process-connection-type in 非同期プロセスの作成). If process represents a program running on a remote host, the terminal name used by that program on the remote host is provided as process property remote-tty. If process represents a network, serial, or pipe connection, the value is nil.

Function: process-coding-system process: この関数は、processからの出力のデコードに使用するコーディングシステム、processへの入力のエンコードに使用するコーディングシステムを記述するコンスセル(decode . encode)をリターンする(コーディングシステムを参照)。

Function: set-process-coding-system process &optional decoding-system encoding-system: この関数は、processにたいする後続の入出力に使用するコーディングシステムを指定する。これはサブプロセスの出力のデコードにdecoding-system、入力のエンコードにencoding-systemを使用するだろう。

すべてのプロセスには、そのプロセスに関連するさまざまな値を格納するために使用できる、プロパティリストもあります。

Function: process-get process propname: この関数は、processのプロパティpropnameの値をリターンする。

Function: process-put process propname value: この関数は、processのプロパティpropnameの値にvalueをセットする。

Function: process-plist process: この関数は、processのプロセスplistをリターンする。

Function: set-process-plist process plist: この関数は、processのプロセスplistにplistをセットする。

38.7 プロセスへの入力の送信

Asynchronous subprocesses receive input when it is sent to them by Emacs, which is done with the functions in this section. You must specify the process to send input to, and the input data to send. If the subprocess runs a program, the data appears on the standard input of that program; for connections, the data is sent to the connected device or program.

オペレーティングシステムには、ptyのバッファーされた入力にたいして制限をもつものがいくつかあります。それらのシステムでは、Emacsは他の文字列の間に定期的かつ強制的に、EOFを送信します。ほとんどのプログラムにたいして、これらのEOFは無害です。

サブプロセスの入力は通常、テキストをファイルに書き込むときと同じように、サブプロセスが受信する前に、コーディングシステムを使用してエンコードされます。どのコーディングシステムを使用するかを指定するには、set-process-coding-systemを使用できます(プロセスの情報を参照)。それ以外の場合、非nilならcoding-system-for-writeがコーディングシステムとなり、さもなくばデフォルトのメカニズムがコーディングシステムを決定します(デフォルトのコーディングシステムを参照)。

入力バッファーが一杯のため、システムがプロセスからの入力を受け取ることができないことがあります。これが発生したときは、送信関数はしばらく待機して、サブプロセスの出力を受け取り、再度送信を試みます。これは保留となっている更なる入力を読み取り、バッファーに空きを作る機会をサブプロセスに与えます。これはフィルター、センチネル、タイマーの実行も可能にするので、コードを記述する際はそれを考慮してください。

以下の関数では、process引数はプロセス、プロセス名、またはバッファー、バッファー名(これはget-buffer-processで取得されるプロセスを意味する)。nilは、カレントバッファーのプロセスを意味します。

Function: process-send-string process string

この関数はstringのコンテンツを、標準入力としてprocessに送信する。たとえばファイルをリストするShellバッファーを作成するには:

(process-send-string "shell<1>" "ls\n")
     ⇒ nil

Function: process-send-region process start end

この関数はstartとendで定義されるリージョンのテキストを、標準入力としてprocessに送信する。

startとendが、カレントバッファー内の位置を示す整数かマーカーでなければ、エラーがシグナルされる(いずれかの大小は重要ではない)。

Function: process-send-eof &optional process

この関数は、processが入力内のEOF(end-of-file)を見ることを可能にする。EOFは、すべての送信済みテキストの後になる。この関数はprocessをリターンする。

(process-send-eof "shell")
     ⇒ "shell"

Function: process-running-child-p &optional process: This function will tell you whether a process, which must not be a connection but a real subprocess, has given control of its terminal to a child process of its own. If this is true, the function returns the numeric ID of the foreground process group of process; it returns nil if Emacs can be certain that this is not so. The value is t if Emacs cannot tell whether this is true. This function signals an error if process is a network, serial, or pipe connection, or is the subprocess is not active.

38.8 プロセスへのシグナルの送信

サブプロセスへのシグナル送信(sending a signal)は、プロセスの活動に割り込む手段の1つです。異なる複数のシグナルがあり、それぞれが独自の意味をもっています。シグナルのセットとそれらの意味は、オペレーティングシステムにより定義されます。たとえばシグナルSIGINTは、ユーザーがC-cをタイプしたか、それに類似する何かが発生したことを意味します。

各シグナルは、サブプロセスに標準的な効果をもちます。ほとんどのシグナルはサブプロセスをkillしますが、かわりに実行を停止(あるいは再開)するものもいくつかあります。ほとんどのシグナルは、オプションでプログラムによりハンドル((処理)することができます。プログラムがそのシグナルをハンドルする場合、その影響についてわたしたちは一般的には何も言うことはできません。

このセクション内の関数を呼び出すことにより、明示的にシグナルを送信できます。Emacsも、特定のタイミングで自動的にシグナルを送信します。バッファーのkillにより、それに関連するプロセスにはSIGHUPシグナルが送信され、Emacsのkillにより、残されたすべてのプロセスにSIGHUPシグナルが送信されます(SIGHUPは通常、ユーザーが“hung up the phone”、電話を切った、つまり接続を断ったことを示す)。

シグナル送信関数はそれぞれprocessとcurrent-groupいう、2つのオプション引数を受け取ります。

The argument process must be either a process, a process name, a buffer, a buffer name, or nil. A buffer or buffer name stands for a process through get-buffer-process. nil stands for the process associated with the current buffer. Except with stop-process and continue-process, an error is signaled if process does not identify an active process, or if it represents a network, serial, or pipe connection.

The argument current-group is a flag that makes a difference when you are running a job-control shell as an Emacs subprocess. If it is non-nil, then the signal is sent to the current process-group of the terminal that Emacs uses to communicate with the subprocess. If the process is a job-control shell, this means the shell’s current subjob. If current-group is nil, the signal is sent to the process group of the immediate subprocess of Emacs. If the subprocess is a job-control shell, this is the shell itself. If current-group is lambda, the signal is sent to the process-group that owns the terminal, but only if it is not the shell itself.

サブプロセスとの対話にpipeが使用されている際は、オペレーティングシステムがpipeでの区別をサポートしないので、フラグcurrent-groupに効果はありません。同じ理由により、pipeが使用されている場合は、ジョブ制御shellは機能しないでしょう。非同期プロセスの作成内のprocess-connection-typeを参照してください。

Function: interrupt-process &optional process current-group: This function interrupts the process process by sending the signal SIGINT. Outside of Emacs, typing the interrupt character (normally C-c on some systems, and DEL on others) sends this signal. When the argument current-group is non-nil, you can think of this function as typing C-c on the terminal by which Emacs talks to the subprocess.

Function: kill-process &optional process current-group: この関数は、シグナルSIGKILLを送信することにより、プロセスprocessをkillする。このシグナルは即座にサブプロセスをkillして、サブプロセスでハンドルすることはできない。

Function: quit-process &optional process current-group: This function sends the signal SIGQUIT to the process process. This signal is the one sent by the quit character (usually C-\) when you are not inside Emacs.

Function: stop-process &optional process current-group

This function stops the specified process. If it is a real subprocess running a program, it sends the signal SIGTSTP to that subprocess. If process represents a network, serial, or pipe connection, this function inhibits handling of the incoming data from the connection; for a network server, this means not accepting new connections. Use continue-process to resume normal execution.

Outside of Emacs, on systems with job control, the stop character (usually C-z) normally sends the SIGTSTP signal to a subprocess. When current-group is non-nil, you can think of this function as typing C-z on the terminal Emacs uses to communicate with the subprocess.

Function: continue-process &optional process current-group: This function resumes execution of the process process. If it is a real subprocess running a program, it sends the signal SIGCONT to that subprocess; this presumes that process was stopped previously. If process represents a network, serial, or pipe connection, this function resumes handling of the incoming data from the connection. For serial connections, data that arrived during the time the process was stopped might be lost.

Command: signal-process process signal

この関数は、プロセスprocessにシグナルを送信する。引数signalは、どのシグナルを送信するかを指定する。これは整数、または名前がシグナルであるようなシンボルであること。

process引数にはシステムプロセスID(整数)を指定できる。これによりEmacsの子プロセス以外のプロセスにシグナルを送信できる。別のプセスへのアクセスを参照のこと。

Sometimes, it is necessary to send a signal to a non-local asynchronous process. This is possible by writing an own interrupt-process implementation. This function must be added then to interrupt-process-functions.

Variable: interrupt-process-functions

This variable is a list of functions to be called for interrupt-process. The arguments of the functions are the same as for interrupt-process. These functions are called in the order of the list, until one of them returns non-nil. The default function, which shall always be the last in this list, is internal-default-interrupt-process.

This is the mechanism, how Tramp implements interrupt-process.

38.9 プロセスからの出力の受信

The output that an asynchronous subprocess writes to its standard output stream is passed to a function called the filter function. The default filter function simply inserts the output into a buffer, which is called the associated buffer of the process (see section プロセスのバッファー). If the process has no buffer then the default filter discards the output.

If the subprocess writes to its standard error stream, by default the error output is also passed to the process filter function. If Emacs uses a pseudo-TTY (pty) for communication with the subprocess, then it is impossible to separate the standard output and standard error streams of the subprocess, because a pseudo-TTY has only one output channel. In that case, if you want to keep the output to those streams separate, you should redirect one of them to a file—for example, by using an appropriate shell command via start-process-shell-command or a similar function.

Alternatively, you could use the :stderr parameter with a non-nil value in a call to make-process (see section make-process) to make the destination of the error output separate from the standard output; in that case, Emacs will use pipes for communicating with the subprocess.

サブプロセス終了時、Emacsは保留中の出力を読み取り、その後そのサブプロセスからの出力の読み取りを停止します。したがって、そのサブプロセスに生きた子プロセスがあり、まだ出力を生成するような場合、Emacsはその出力を受け取らないでしょう。

サブプロセスからの出力は、Emacsが待機している間、端末入力読み取り時(関数waiting-for-user-input-p、時間の経過や入力の待機のsit-forとsleep-for、およびプロセスからの出力を受け入れるのaccept-process-outputを参照されたい)のみ到着可能です。これは、並列プログラミングで普遍的に悩みの種である、タイミングエラーの問題を最小化します。たとえば、安全にプロセスを作成して、その後でのみプロセスのバッファーやフィルター関数を指定できます。その間にあるコードが待機するプリミティブを何も呼び出さなければ、完了するまで到着可能な出力はありません。

Variable: process-adaptive-read-buffering: いくつかのシステムでは、Emacsがサブプロセスの出力を読み取る際、出力データを非常に小さいブロックで読み取るため、結果として潜在的に非常に貧弱なパフォーマンスとなることがる。この挙動は、変数process-adaptive-read-bufferingを非nil値(デフォルト)にセットして拡張することにより改善し得る。これにより、そのようなプロセスからの読み取りを自動的に遅延して、Emacsが読み取りを試みる前に、出力がより生成されるようになる。

38.9.1 プロセスのバッファー		デフォルトでは、出力はバッファーに送信される。
38.9.2 プロセスのフィルター関数		フィルター関数はプロセスからの出力を受け取る。
38.9.3 プロセス出力のデコード		フィルターはユニバイトおよびマルチバイトの文字列を取得できる。
38.9.4 プロセスからの出力を受け入れる		プロセスの出力到着まで待機する方法。
38.9.5 Processes and Threads		How processes and threads interact.

38.9.1 プロセスのバッファー

プロセスは関連付けられたバッファー(associated buffer)をもつことができます(通常はもつ)。これは普通のEmacsバッファーであり、2つの目的のために使用されます。1つはプロセスからの出力の格納、もう1つはプロセスをkillする時期を判断するためです。通常の習慣では、任意の与えられたバッファーにたいして関連付けられるプロセスは1つだけなので、処理対象のプロセスを識別するためにそのバッファーを使用することもできます。プロセス使用の多くはプロセスに送信する入力を編集するためにもこのバッファーを使用しますが、これはEmacs Lispに組み込まれてはいません。

デフォルトでは、プロセスの出力は関連付けられたバッファーに挿入されます(カスタムフィルター関数の定義により変更可能。プロセスのフィルター関数を参照されたい)。出力を挿入する位置は、process-markにより決定されます。これは正に挿入されたテキストの終端に、ポイントを更新します。通常、ただし常にではありませんが、process-markはバッファーの終端になります。

プロセスに関連付けられたバッファーをkillすることにより、そのプロセスもkillされます。そのプロセスのprocess-query-on-exit-flagが非nilなら、Emacsはまず確認を求めます(exit前の問い合わせを参照)。この確認は関数process-kill-buffer-query-functionにより行われ、これはkill-buffer-query-functionsから実行されます(バッファーのkillを参照)。

Function: process-buffer process

This function returns the associated buffer of the specified process.

(process-buffer (get-process "shell"))
     ⇒ #<buffer *shell*>

Function: process-mark process

この関数は、processにたいするプロセスマーカーをリターンする。これはプロセスからの出力をどこに挿入するかを示すマーカーである。

processバッファーをもたなければ、process-markは存在しない場所を指すマーカーをリターンする。

デフォルトフィルター関数は、プロセス出力の挿入場所の決定にこのマーカーを使用し、挿入したテキストの後にポイントを更新する。連続するバッチ出力が、連続して挿入されるのは、これが理由である。

カスタムフィルター関数は、このマーカーを通常は同じ方式で使用するべきである。process-markを使用するフィルター関数の例は、Process Filter Exampleを参照のこと。

ユーザーにプロセスバッファー内でプロセスに送信するための入力を期待する際は、プロセスマーカーは以前の出力から新たな入力を区別する。

Function: set-process-buffer process buffer: この関数は、processに関連付けられたバッファーに、bufferをセットする。bufferがnilなら、プロセスはバッファーに関連付けられない。

Function: get-buffer-process buffer-or-name

この関数は、buffer-or-nameで指定されるバッファーに関連付けられた、削除されていないプロセスをリターンする。そのバッファーに複数のプロセスが関連付けられている場合、この関数はいずれか1つ(現在のところもっとも最近作成されたプロセスだが、これを当てにしないこと)を選択する。プロセスの削除(delete-processを参照)により、そのプロセスはこの関数がリターンするプロセスとしては不適格となる。

同一のバッファーに複数のプロセスを関連付けるのは、通常は悪いアイデアである。

(get-buffer-process "*shell*")
     ⇒ #<process shell>

プロセスのバッファーをkillすることにより、SIGHUPシグナルでサブプロセスをkillして、プロセスを削除する(プロセスへのシグナルの送信を参照)。

If the process’s buffer is displayed in a window, your Lisp program may wish to tell the process the dimensions of that window, so that the process could adapt its output to those dimensions, much as it adapts to the screen dimensions. The following functions allow communicating this kind of information to processes; however, not all systems support the underlying functionality, so it is best to provide fallbacks, e.g., via command-line arguments or environment variables.

Function: set-process-window-size process height width: Tell process that its logical window size has dimensions width by height, in character units. If this function succeeds in communicating this information to the process, it returns t; otherwise it returns nil.

When windows that display buffers associated with process change their dimensions, the affected processes should be told about these changes. By default, when the window configuration changes, Emacs will automatically call set-process-window-size on behalf of every process whose buffer is displayed in a window, passing it the smallest dimensions of all the windows displaying the process’s buffer. This works via window-configuration-change-hook (see section ウィンドウのスクロールと変更のためのフック), which is told to invoke the function that is the value of the variable window-adjust-process-window-size-function for each process whose buffer is displayed in at least one window. You can customize this behavior by setting the value of that variable.

User Option: window-adjust-process-window-size-function

The value of this variable should be a function of two arguments: a process and the list of windows displaying the process’s buffer. When the function is called, the process’s buffer is the current buffer. The function should return a cons cell (width . height) that describes the dimensions of the logical process window to be passed via a call to set-process-window-size. The function can also return nil, in which case Emacs will not call set-process-window-size for this process.

Emacs supplies two predefined values for this variable: window-adjust-process-window-size-smallest, which returns the smallest of all the dimensions of the windows that display a process’s buffer; and window-adjust-process-window-size-largest, which returns the largest dimensions. For more complex strategies, write your own function.

This variable can be buffer-local.

If the process has the adjust-window-size-function property (see section プロセスの情報), its value overrides the global and buffer-local values of window-adjust-process-window-size-function.

38.9.2 プロセスのフィルター関数

プロセスのフィルター関数(filter function)は、関連付けられたプロセスからの標準出力を受信します。そのプロセスのすべての出力は、そのフィルターに渡されます。デフォルトのフィルターは単に、プロセスバッファーに直接出力します。

By default, the error output from the process, if any, is also passed to the filter function, unless the destination for the standard error stream of the process was separated from the standard output when the process was created (see section プロセスからの出力の受信).

サブプロセスからの出力は、Emacsが何かを待機している間だけ到着するので、フィルター関数はそのようなときだけ呼び出し可能です。Emacsは端末入力読み取り時(関数waiting-for-user-input-p、時間の経過や入力の待機のsit-forとsleep-for、およびプロセスからの出力を受け入れるのaccept-process-outputを参照されたい)に待機します。

フィルター関数は関連付けられたプロセス、およびそのプロセスから正に受信した出力である文字列という、2つの引数を受け取らなければなりません。関数はその後、出力にたいして何であれ、自由に行うことができます。

quitは通常はフィルター関数内では抑制されます。さもないと、コマンドレベルでのC-gのタイプ、またはユーザーコマンドのquitは予測できません。フィルター関数内部でのquitを許可したければ、inhibit-quitをnilにバインドしてください。ほとんどの場合において、これを行う正しい方法はマクロwith-local-quitです。quitを参照してください。

If an error happens during execution of a filter function, it is caught automatically, so that it doesn’t stop the execution of whatever program was running when the filter function was started. However, if debug-on-error is non-nil, errors are not caught. This makes it possible to use the Lisp debugger to debug filter functions. See section Lispデバッガ.

多くのフィルター関数は時折(または常に)、デフォルトフィルターの動作を真似て、プロセスのバッファーにその出力を挿入します。そのようなフィルター関数は確実にカレントバッファーの保存と、(もし異なるなら)出力を挿入する前に正しいバッファーを選択して、その後に元のバッファーをリストアする必要があります。また、そのバッファーがまだ生きているか、プロセスマーカーを更新しているか、そしていくつかのケースにおいてはポイントの値を更新しているかもチェックするべきです。以下はこれらを行う方法です:

(defun ordinary-insertion-filter (proc string)
  (when (buffer-live-p (process-buffer proc))
    (with-current-buffer (process-buffer proc)
      (let ((moving (= (point) (process-mark proc))))

        (save-excursion
          ;; テキストを挿入してプロセスマーカーを進める
          (goto-char (process-mark proc))
          (insert string)
          (set-marker (process-mark proc) (point)))
        (if moving (goto-char (process-mark proc)))))))

新たなテキスト到着時にフィルターが強制的にプロセスバッファーを可視にするために、with-current-buffer構成の直前に以下のような行を挿入できます:

(display-buffer (process-buffer proc))

To force point to the end of the new output, no matter where it was previously, eliminate the variable moving from the example and call goto-char unconditionally.

フィルター関数実行中、Emacsは自動的にマッチデータの保存とリストアを行うことに注意してください。マッチデータを参照してください。

フィルターへの出力は、任意のサイズのchunkで到着する可能性があります。同じ出力を連続して2回生成するプログラムは、一度に200文字を1回のバッチで送信して、次に40文字を5回のバッチで送信するかもしれません。フィルターが特定のテキスト文字列をサブプロセスの出力から探す場合は、それらの文字列が2回以上のバッチ出力を横断するケースに留意して処理してください。これを行うには、受信したテキストを一時的なバッファーに挿入してから、それを検索するのが1つの方法です。

Function: set-process-filter process filter: この関数は、processにフィルター関数filterを与える。filterがnilならそのプロセスにたいして、プロセスバッファーにプロセス出力を挿入する、デフォルトフィルターを与える。

Function: process-filter process: この関数は、processのフィルター関数をリターンする。

そのプロセスの出力を複数のフィルターに渡す必要がある場合は、既存のフィルターに新たなフィルターを組み合わせるために、add-functionを使用できる。Emacs Lisp関数にたいするアドバイスを参照のこと。

以下は、フィルター関数の使用例である:

(defun keep-output (process output)
   (setq kept (cons output kept)))
     ⇒ keep-output

(setq kept nil)
     ⇒ nil

(set-process-filter (get-process "shell") 'keep-output)
     ⇒ keep-output

(process-send-string "shell" "ls ~/other\n")
     ⇒ nil
kept
     ⇒ ("lewis@slug:$ "

"FINAL-W87-SHORT.MSS    backup.otl              kolstad.mss~
address.txt             backup.psf              kolstad.psf
backup.bib~             david.mss               resume-Dec-86.mss~
backup.err              david.psf               resume-Dec.psf
backup.mss              dland                   syllabus.mss
"
"#backups.mss#          backup.mss~             kolstad.mss
")

38.9.3 プロセス出力のデコード

Emacsが直接マルチバイトバッファーにプロセス出力を書き込む際は、プロセス出力のコーディングシステムに応じて、出力をデコードします。コーディングシステムがraw-textかno-conversionなら、Emacsはstring-to-multibyteを使用してユニバイト出力をマルチバイトに変換して、その結果のマルチバイトテキストを挿入します。

どのコーディングシステムを使用するかは、set-process-coding-systemを使用して指定できます(プロセスの情報を参照)。それ以外では、coding-system-for-readが非nilならそのコーディングシステム、nilならデフォルトのメカニズムが使用されます(デフォルトのコーディングシステムを参照)。プロセスのテキスト出力にnullバイトが含まれる場合、Emacsはそれにたいしてデフォルトではno-conversionを使用します。この挙動を制御する方法については、inhibit-null-byte-detectionを参照してください。

警告: データからコーディングシステムをundecidedのようなコーディングシステムは、非同期サブプロセスの出力にたいして完全な信頼性をもって機能しません。これはEmacsが、到着に応じて非同期サブプロセスの出力をバッチで処理する必要があるからです。Emacsは1つのバッチが到着するたびに正しいコーディングシステムを検出しなければならず、これは常には機能しません。したがって、可能であれば文字コード変換とEOL変換の両方を決定するコーディングシステム、つまりlatin-1-unix、undecided、latin-1のようなコーディングシステムを指定してください。

Emacsがプロセスフィルター関数を呼び出す際は、そのプロセスのフィルターのコーディングシステムに応じて、Emacsはプロセス出力をマルチバイト文字列、またはユニバイト文字列で提供します。Emacsはプロセス出力のコーディングシステムに応じて出力をデコードします。これはbinaryやraw-textのようなコーディングシステムを除き、通常はマルチバイト文字列を生成します。

38.9.4 プロセスからの出力を受け入れる

非同期サブプロセスからの出力は通常、Emacsが時間の経過や端末入力のような、ある種の外部イベントを待機する間だけ到着します。特定のポイントで出力の到着を明示的に許可したり、あるいはプロセスからの出力が到着するまで待機することさえ、Lispプログラムでは有用な場合が時折あります。

Function: accept-process-output &optional process seconds millisec just-this-one

この関数はプロセスからの保留中の出力を、Emacsが読み取ることを許す。この出力は、プロセスのフィルター関数により与えられる。processが非nilなら、この関数はprocessから何らかの出力を受け取るまでリターンしない。

The arguments seconds and millisec let you specify timeout periods. The former specifies a period measured in seconds and the latter specifies one measured in milliseconds. The two time periods thus specified are added together, and accept-process-output returns after that much time, even if there is no subprocess output.

secondsに浮動小数点数を指定することにより、秒を少数点で指定できるので、引数millisecは時代遅れである(そして使用するべきではない)。secondsが0なら、この関数は保留中の出力が何であれ受け取り、待機しない。

processがプロセスで、引数just-this-oneが非nilなら、そのプロセスからの出力だけが処理され、そのプロセスからの出力を受信するか、タイムアウトとなるまで、他のプロセスの出力は停止される。just-this-oneが整数なら、タイマーの実行も抑制される。この機能は一般的には推奨されないが、音声合成のような特定のアプリケーションにとっては必要かもしれない。

The function accept-process-output returns non-nil if it got output from process, or from any process if process is nil. It returns nil if the timeout expired before output arrived.

38.9.5 Processes and Threads

Because threads were a relatively late addition to Emacs Lisp, and due to the way dynamic binding was sometimes used in conjunction with accept-process-output, by default a process is locked to the thread that created it. When a process is locked to a thread, output from the process can only be accepted by that thread.

A Lisp program can specify to which thread a process is to be locked, or instruct Emacs to unlock a process, in which case its output can be processed by any thread. Only a single thread will wait for output from a given process at one time—once one thread begins waiting for output, the process is temporarily locked until accept-process-output or sit-for returns.

If the thread exits, all the processes locked to it are unlocked.

Function: process-thread process: Return the thread to which process is locked. If process is unlocked, return nil.

Function: set-process-thread process thread: Set the locking thread of process to thread. thread may be nil, in which case the process is unlocked.

38.10 センチネル: プロセス状態の変更の検知

プロセスセンチネル(process sentinel: プロセス番兵)とは、(Emacsにより送信されたか、そのプロセス自身の動作が原因で送信された)プロセスを終了、停止、継続するシグナルを含む、何らかの理由により関連付けられたプロセスの状態が変化した際は常に呼び出される関数のことです。プロセスがexitする際にも、プロセスセンチネルが呼び出されます。センチネルは、イベントが発生したプロセスと、イベントのタイプを記述する文字列という、2つの引数を受け取ります。

If no sentinel function was specified for a process, it will use the default sentinel function, which inserts a message in the process’s buffer with the process name and the string describing the event.

イベントを記述する文字列は、以下のいずれかのような外見をもちます:

"finished\n".
"deleted\n".
"exited abnormally with code exitcode (core dumped)\n". The “core dumped” part is optional, and only appears if the process dumped core.
"failed with code fail-code\n".
"signal-description (core dumped)\n". The signal-description is a system-dependent textual description of a signal, e.g., "killed" for SIGKILL. The “core dumped” part is optional, and only appears if the process dumped core.
"open from host-name\n".
"open\n".
"connection broken by remote peer\n".

センチネルは、Emacsが(端末入力や時間経過、またはプロセス出力を)待機している間だけ実行されます。これは、他のLispプログラムの途中のランダムな箇所で実行されるセンチネルが原因となる、タイミングエラーを無視します。プログラムはセンチネルが実行されるように、sit-forやsleep-for(時間の経過や入力の待機を参照)、またはaccept-process-output(プロセスからの出力を受け入れるを参照)を呼び出すことにより待機することができます。Emacsはコマンドループが入力を読み取る際にも、センチネルの実行を許可します。delete-processは、実行中のプログラムを終了させる際に、センチネルを呼び出します。

Emacsは1つのプロセスのセンチネル呼び出しの理由のために複数のキューを保持しません。これはカレント状態と、変化があった事実だけを記録します。したがって非常に短い間隔で、連続して状態に2つの変化があった場合は、一度だけセンチネルが呼び出されます。しかしプロセスの終了は、常に正確に1回センチネルを実行するでしょう。これは終了後にプロセス状態が再び変更されることはないからです。

Emacsはプロセスセンチネル実行の前に、プロセスからの出力をチェックします。プロセス終了によりセンチネルが一度実行されると、そのプロセスから更なる出力は到着しません。

プロセスのバッファーに出力を書き込むセンチネルは、そのバッファーがまだ生きているかチェックするべきです。死んだバッファーへの挿入を試みた場合は、エラーとなるでしょう。そのバッファーがすでに死んでいれば、(buffer-name (process-buffer process))はnilをリターンします。

quitは通常はセンチネル内では抑制されます。さもないと、コマンドレベルでのC-gのタイプ、またはユーザーコマンドのquitは予測できません。センチネル内部でのquitを許可したければ、inhibit-quitをnilにバインドしてください。ほとんどの場合において、これを行う正しい方法はマクロwith-local-quitです。quitを参照してください。

センチネルの実行中にエラーが発生した場合、センチネル開始時に実行中だったプログラムが何であれ実行を停止しないように、自動的にcatchされます。しかしdebug-on-errorが非nilなら、エラーはcatchされません。これにより、Lispデバッガーを使用したセンチネルのデバッグが可能になります。Lispデバッガを参照してください。

センチネル実行中、センチネルが再帰的に実行されないよう、プロセスセンチネルは一時的にnilにセットされます。この理由により、センチネルが新たにセンチネルを指定することはできません。

センチネル実行中、Emacsは自動的にマッチデータの保存とリストアを行うことに注意してください。マッチデータを参照してください。

Function: set-process-sentinel process sentinel

この関数は、processに関連付ける。sentinelがnilなら、そのプロセスはプロセス状態変更時にプロセスのバッファーにメッセージを挿入する、デフォルトのセンチネルをもつことになるだろう。

プロセスセンチネルの変更は、即座に効果を発揮する。そのセンチネルが実行される予定だが、まだ呼び出されておらず、かつ新たなセンチネルを指定した場合、最終的なセンチネル呼び出しには、新たなセンチネルが使用されるだろう。

(defun msg-me (process event)
   (princ
     (format "Process: %s had the event '%s'" process event)))
(set-process-sentinel (get-process "shell") 'msg-me)
     ⇒ msg-me

(kill-process (get-process "shell"))
     -| Process: #<process shell> had the event 'killed'
     ⇒ #<process shell>

Function: process-sentinel process: この関数は、processのセンチネルをリターンする。

あるプロセス状態の変化を複数のセンチネルに渡す必要がある場合は、既存のセンチネルと新たなセンチネルを組み合わせるために、add-functionを使用できます。Emacs Lisp関数にたいするアドバイスを参照してください。

Function: waiting-for-user-input-p: この関数は、センチネルまたはフィルター関数の実行中、もしEmacsがセンチネルまたはフィルター関数呼び出し時にユーザーのキーボード入力を待機していたら非nil、そうでなければnilをリターンする。

38.11 exit前の問い合わせ

When Emacs exits, it terminates all its subprocesses. For subprocesses that run a program, it sends them the SIGHUP signal; connections are simply closed. Because subprocesses may be doing valuable work, Emacs normally asks the user to confirm that it is ok to terminate them. Each process has a query flag, which, if non-nil, says that Emacs should ask for confirmation before exiting and thus killing that process. The default for the query flag is t, meaning do query.

Function: process-query-on-exit-flag process: これは、processのqueryフラグをリターンする。

Function: set-process-query-on-exit-flag process flag

この関数は、processのqueryフラグをflagにセットする。これはflagをリターンする。

以下はshellプロセス上で、問い合わせを回避するためにset-process-query-on-exit-flagを使用する例である:

(set-process-query-on-exit-flag (get-process "shell") nil)
     ⇒ nil

User Option: confirm-kill-processes: If this user option is set to t (the default), then Emacs asks for confirmation before killing processes on exit. If it is nil, Emacs kills processes without confirmation, i.e., the query flag of all processes is ignored.

38.12 別のプセスへのアクセス

カレントEmacsセッションのサブプロセスにたいするアクセスと操作に加えて、同一マシン上で実行中の他のプロセスにたいして、Emacs Lispプログラムがアクセスすることもできます。Emacsのサブプロセスと区別するために、わたしたちはこれらをシステムプロセス(system processes)と呼んでいます。

Emacsは、システムプロセスへのアクセス用のプリミティブをいくつか提供します。これらのプリミティブは、すべてのプラットフォームではサポートされません。サポートしないシステムでは、これらのプリミティブはnilをリターンします。

Function: list-system-processes: この関数は、そのシステム上で実行中の、すべてのプロセスのリストをリターンする。各プロセスは、PIDというOSから割り当てられた数値によるプロセスIDにより識別され、同一時に同一マシン上で実行中の他のプロセスと区別される。

Function: process-attributes pid

この関数は、プロセスID pidで指定されるプロセスにたいする、属性のalistをリターンする。このalist内の各属性は(key . value)という形式で、keyは属性を指定し、valueはその属性の値である。この関数がリターン可能な、さまざまな属性にたいするkeyを、以下にリストした。これらすべての属性を、すべてのプラットフォームがサポートする訳ではない。ある属性がサポートされていなければ、その連想値はリターンされるalist内に出現しない。数値であるような値は整数か浮動小数点数のいずれかが可能で、それは値の大小に依存する。

euid

そのプロセスを呼び出したユーザーの、実効ユーザーID(effective user ID)。対応するvalueは数値。プロセスがカレントEmacsセッションを実行したユーザーと同じなら、値はuser-uidがリターンする値と等しくなる(ユーザーの識別を参照)。

user

そのプロセスの実効ユーザーIDに対応するユーザー名であるような文字列。

egid

実行ユーザーIDのグループIDであるような数値。

group

実効ユーザーのグループIDに対応するグループ名であるような文字列。

comm

そのプロセス内で実効したコマンドの名前。これは通常、先行するディレクトリーを除いた実行可能ファイル名を指定する文字列である。しかし、いくつかの特別なシステムプロセスは、実行可能ファイルまたはプログラムに対応しない文字列を報告する可能性がある。

state

そのプロセスの状態コード。これはそのプロセスのスケジューリング状態をエンコードする短い文字列である。以下は頻繁に目にするコードのリストである:

"D": 割り込み不可のsleep(通常はI/Oによる)
"R": 実行中
"S": 割り込み可能なsleep(何らかのイベント待ち)
"T": たとえばジョブ制御シグナルにより停止された
"Z": zombie: a process that terminated, but was not reaped by its parent

可能な状態の完全なリストは、psコマンドのman pageを参照されたい。

ppid

親プロセスのプロセスIDであるような数値。

pgrp

そのプロセスのプロセスグループIDであるような数値。

sess

そのプロセスのセッションID。これはそのプロセスのセッションリーダー(session leader)のプロセスIDであるような数値である。

ttname

そのプロセスの制御端末の名前であるような文字列。UnixおよびGNUシステムでは、これは通常は/dev/pts65のような、対応する端末デバイスのファイル名である。

tpgid

そのプロセスの端末を使用するフォアグラウンドプロセスグループの、プロセスグループIDであるような数値。

minflt

そのプロセス開始以降に発生したマイナーなページフォルト数(マイナーなページフォルトとはディスクからの読み込みを発生させないページフォルトのこと)。

majflt

そのプロセス開始以降に発生したメジャーなページフォルト数(メジャーなページフォルトとは、ディスクからの読み込みを要し、それ故にマイナーページフォルトより高価なページフォルトのこと)。

cminflt

cmajflt

minfltとmajfltと似ているが、与えられたプロセスのすべての子プロセスのページフォルト数を含む。

utime

アプリケーションのコード実行にたいして、ユーザーコンテキスト内でプロセスに消費された時間。対応するvalueは(high low microsec picosec)というフォーマットで、これは関数current-timeが使用するフォーマットと同じである(current-time)およびファイルの属性のfile-attributesを参照)。

stime

システムコールの処理にたいして、システム(kernel)コンテキスト内でプロセスに消費された時間。対応するvalueはutimeと同じフォーマット。

time

utimeとstimeの和。対応するvalueはutimeと同じフォーマット。

cutime

cstime

ctime

utimeやstimeと同様だが、与えられたプロセスのすべての子プロセスの時間が含まれる点が異なる。

pri

そのプロセスの数値的な優先度。

nice

そのプロセスのnice値(nice value)であるような数値(小さいnice値のプロセスがより優先的にスケジュールされる)。

thcount

そのプロセス内のスレッド数。

start

file-attributesおよびcurrent-timeが使用するのと同じフォーマット(high low microsec picosec)による、そのプロセスが開始された時刻。

etime

(high low microsec picosec)というフォーマットによる、そのプロセスが開始されてから経過した時間。

vsize

そのプロセスの仮想メモリーのKB単位でのサイズ。

rss

そのプロセスがマシンの物理メモリー内で占める常駐セット(resident set)のKB単位でのサイズ。

pcpu

プロセス開始以降に使用されたCPU時間のパーセンテージ。対応するvalueは0から100の間の浮動小数点数。

pmem

マシンにインストールされた物理メモリー合計のうち、そのプロセスの常駐セットのパーセンテージ。値は0から100の間の浮動小数点数。

args

そのプロセスが呼び出されたときのコマンドライン。これは個々のコマンドライン引数がブランクで区切られた文字列である。引数に埋め込まれた空白文字は、そのシステムに応じて適切にクォートされる。GNUおよびUnixではバックスラッシュ文字によるエスケープ、Windowsではダブルクォート文字で囲まれる。つまりこのコマンドライン文字列は、shell-commandのようなプリミティブにより直接使用できる。

38.13 トランザクションキュー

トランザクションを用いてサブプロセスと対話するために、トランザクションキュー(transaction queue)を使用できます。まずtq-createを使用して、指定したプロセスと対話するためのトランザクションキューを作成します。それからトランザクションを送信するために、tq-enqueueを呼び出すことができます。

Function: tq-create process: この関数は、processと対話するトランザクションキューを作成してリターンする。引数processは、バイトストリームを送受信する能力をもつサブプロセスであること。これは子プロセス、または(おそらく別のマシン上の)サーバーへのTCP接続かもしれない。

Function: tq-enqueue queue question regexp closure fn &optional delay-question

この関数は、キューqueueにトランザクションを送信する。キューの指定は、対話するサブプロセスを指定する効果をもつ。

引数questionは、トランザクションを開始するために発信するメッセージである。引数fnは、それにたいする応答が返信された際に呼び出す関数である。これはclosureと受信した応答という、2つの引数で呼び出される。

引数regexpは応答全体の終端にマッチし、それより前にはマッチしない正規表現であること。これが応答の終わりをtq-enqueueが決定する方法である。

引数delay-questionが非nilなら、そのプロセスが以前に発信したすべてのメッセージへの返信が完了するまで、このメッセージの送信を遅延する。これは、いくつかのプロセスにたいしてより信頼性のある結果が生成される。

Function: tq-close queue: 保留中のすべてのトランザクションの完了を待機して、トランザクションキューqueueをシャットダウンし、それから接続または子プロセスを終了する。

トランザクションキューは、フィルター関数により実装されています。プロセスのフィルター関数を参照してください。

38.14 ネットワーク接続

Emacs Lispプログラムは、同一マシンまたは他のマシン上の別プロセスにたいして、ストリーム(TCP)およびデータグラム(UDP)のネットワーク接続(データグラムを参照)をオープンできます。ネットワーク接続はLispにより、サブプロセスと同様に処理され、プロセスオブジェクトとして表されます。しかし対話を行うそのプロセスは、Emacsの子プロセスではなく、プロセスIDをもたず、それをkillしたりシグナルを送信することはできません。行うことができるのは、データの送信と受信だけです。delete-processは接続をクローズしますが、他端のプログラムをkillしません。そのプログラムは接続のクローズについて何を行うか、決定しなければなりません。

ネットワークサーバーを作成することにより、Lispプログラムは接続をlistenできます。ネットワークサーバーもある種のプロセスオブジェクトとして表されますが、ネットワーク接続とは異なり、ネットワークサーバーがデータ自体を転送することは決してありません。接続リクエストを受信したときは、それにたいして作成した接続を表す、新たなネットワーク接続を作成します(そのネットワーク接続はサーバーから、プロセスplistを含む特定の情報を継承する)。その後、ネットワークサーバーは更なる接続リクエストのlistenに戻ります。

ネットワーク接続およびサーバーは、キーワード/引数のペアーで構成される引数リストでmake-network-processを呼び出すことにより作成されます。たとえば:server tはサーバープロセス、:type 'datagramはデータグラム接続を作成します。詳細は低レベルのネットワークアクセスを参照してください。以下で説明するopen-network-streamを使用することもできます。

To distinguish the different types of processes, the process-type function returns the symbol network for a network connection or server, serial for a serial port connection, pipe for a pipe connection, or real for a real subprocess.

The process-status function returns open, closed, connect, stop, or failed for network connections. For a network server, the status is always listen. Except for stop, none of those values is possible for a real subprocess. See section プロセスの情報.

stop-processとcontinue-processを呼び出すことにより、ネットワークプロセスの処理の停止と再開が可能です。サーバープロセスにたいする停止は、新たな接続の受け付けないことを意味します(サーバー再開時は5つまでの接続リクエストがキューされる。これがOSによる制限でなければこの制限は増やすことができる。make-network-processのmake-network-processの:serverを参照されたい)。ネットワークストリーム接続にたいしては、停止は入力の処理を行わないことを意味します(到着するすべての入力は接続の再開まで待つ)。データグラム接続にたいしては、いくらかのパケットはキューされますが、入力は失われるかもしれません。ネットワーク接続またはサーバーが停止しているかどうかを判断するために、関数process-commandを使用できます。これが非nilなら停止しています。

Emacs can create encrypted network connections, using either built-in or external support. The built-in support uses the GnuTLS Transport Layer Security Library; see the GnuTLS project page. If your Emacs was compiled with GnuTLS support, the function gnutls-available-p is defined and returns non-nil. For more details, see Overview in The Emacs-GnuTLS manual. The external support uses the starttls.el library, which requires a helper utility such as gnutls-cli to be installed on the system. The open-network-stream function can transparently handle the details of creating encrypted connections for you, using whatever support is available.

Function: open-network-stream name buffer host service &rest parameters

この関数は、オプションで暗号つきでTCP接続をオープンして、その接続を表すプロセスオブジェクトをリターンする。

name引数は、プロセスオブジェクトの名前を指定する。これは必要に応じて一意になるよう修正される。

buffer引数は、その接続に関連付けるバッファーである。その接続からの出力は、その出力を処理する独自のフィルター関数を指定していなければ、bufferがnilなら、その接続はバッファーに関連付けられない。

The arguments host and service specify where to connect to; host is the host name (a string), and service is the name of a defined network service (a string) or a port number (an integer like 80 or an integer string like "80").

残りの引数parametersは、主に暗号化された接続に関連する、キーワード/引数のペアーである:

:nowait boolean

非nilなら非同期接続を試みる。

:type type

接続のタイプ。オプションは以下のとおり:

plain: 通常の暗号化されていない接続。
tls
ssl: A TLS (Transport Layer Security) connection.
nil
network: plain接続を開始して、パラメーター‘:success’および‘:capability-command’が与えられたら、STARTTLSを通じて暗号化接続への更新を試みる。これが失敗したら、暗号化されていない接続のまま留まる。
starttls: nilと同様だが、STARTTLSが失敗したらその接続を切断する。
shell: shell接続。

:always-query-capabilities boolean

非nilなら、たとえ‘plain’な接続を行っているときでも、常にサーバーの能力を問い合わせる。

:capability-command capability-command

ホストの能力を問い合わせるためのコマンド文字列。

:end-of-command regexp

:end-of-capability regexp

コマンドの終端、またはコマンドcapability-commandの終端にマッチする正規表現。前者は後者のデフォルトである。

:starttls-function function

単一の引数(capability-commandにたいする応答)をとりnil、またはサポートされていればSTARTTLSをアクティブにするコマンドをリターンする関数。

:success regexp

成功したSTARTTLSネゴシェーションにマッチする正規表現。

:use-starttls-if-possible boolean

非nilなら、たとえEmacsがビルトインのTLSサポートをもっていなくても、日和見的(opportunistic)にSTARTTLSアップグレードを行う。

:warn-unless-encrypted boolean

If non-nil, and :return-value is also non-nil, Emacs will warn if the connection isn’t encrypted. This is useful for protocols like IMAP and the like, where most users would expect the network traffic to be encrypted.

:client-certificate list-or-t

証明書(certificate)のキーと、証明書のファイル自身を命名する(key-file cert-file)という形式のリスト、またはこの情報にたいしてauth-sourceを尋ねることを意味するtのいずれか(Overview in The Auth-Source Manualを参照)。TLSまたはSTARTTLSにたいしてのみ使用される。

:return-list cons-or-nil

この関数のリターン値。省略またはnilなら、プロセスオブジェクトをリターンする。それ以外なら、(process-object . plist)という形式のコンスセルをリターンする。ここでplistは以下のキーワードである:

:greeting string-or-nil: 非nilなら、ホストからリターンされたgreeting(挨拶)文字列。
:capabilities string-or-nil: 非nilなら、ホストの能力(capability)文字列。
:type symbol: 接続タイプで、‘plain’か‘tls’のいずれか。

:shell-command string-or-nil

If the connection type is shell, this parameter will be interpreted as a format-spec string that will be executed to make the connection. The specs available are ‘%s’ for the host name and ‘%p’ for the port number. For instance, if you want to first ssh to ‘gateway’ before making a plain connection, then this parameter could be something like ‘ssh gateway nc %s %p’.

38.15 ネットワークサーバー

:server tでmake-network-processを呼び出すことによりサーバーが作成されます(make-network-processを参照)。そのサーバーは、クライアントからの接続リクエストをlistenするでしょう。クライアントの接続リクエストをaccept(受け入れる)する際は、以下のようなパラメーターで、それ自体がプロセスオブジェクトであるようなネットワーク接続を作成します。

その接続のプロセス名は、サーバープロセスのnameと、クライアント識別文字列を結合して構築される。IPv4接続にたいするクライアント識別文字列は、アドレスとポート番号を表す、‘<a.b.c.d:p>’のような文字列である。それ以外なら、‘<nnn>’のようにカッコで囲まれた一意な数字である。この数字は、そのEmacsセッション内のそれぞれの接続にたいして一意である。
サーバーが非デフォルトのフィルターをもつ場合、その接続プロセスは別個にプロセスバッファーを取得しない。それ以外なら、Emacsはその目的のために新たにバッファーを作成する。サーバーのバッファー名またはプロセス名にクライアント識別文字列に結合したものがバッファー名になる。
サーバーのプロセスバッファーの値が直接使用されることは決してないが、log関数はそれを取得して、そこにテキストを挿入することにより、接続のログを記録するために使用することができる。
通信タイプ(communication type)、プロセスフィルター、およびセンチネルはそれぞれ、サーバーのものから継承される。サーバーが直接フィルターとセンチネルを使用することは決してない。それらの唯一の目的は、サーバーへの接続を初期化することである。
その接続のプロセスコンタクト情報は、クライアントのアドレス情報(通常はIPアドレスとポート番号)に応じてセットされる。この情報は、process-contactのキーワード:host、:service、:remoteに関連付けられる。
その接続のローカルアドレスは、それが使用するポート番号に応じてセットアップされる。
クライアントプロセスのplistは、サーバーのplistからインストールされる。

38.16 データグラム

データグラム(datagram)接続は、データストリームではなく個別のパッケージで対話します。process-sendを呼び出すたびに1つのデータグラムパケット(see section プロセスへの入力の送信)が送信され、受信されたデータグラムごとに1回フィルター関数が呼び出されます。

データグラム接続は、毎回同じリモートピア(remote peer)と対話する必要はありません。データグラム接続は、データグラムの送信先を指定する、リモートピアアドレス(remote peer address)をもちます。フィルター関数にたいして受信されたデータグラムが渡されるたびに、そのデータグラムの送信元アドレスがピアアドレスにセットされます。このように、もしフィルター関数がデータグラムを送信したら、それは元の場所へ戻ることになります。:remoteキーワードを使用してデータグラム接続を作成する際は、リモートピアアドレスを指定できます。set-process-datagram-addressを呼び出すことにより、後からそれを変更できます。

Function: process-datagram-address process: processがデータグラム接続またはサーバーなら、この関数はそれのリモートピアアドレスをリターンする。

Function: set-process-datagram-address process address: processがデータグラム接続またはサーバーなら、この関数はそのリモートピアアドレスにaddressをセットする。

38.17 低レベルのネットワークアクセス

make-network-processを使用することにより、open-network-streamより低レベルでの処理により、ネットワーク接続を作成することもできます。

38.17.1 `make-network-process`

ネットワーク接続およびネットワークサーバーを作成する基本的な関数は、make-network-processです。これは与えられた引数に応じて、これらの仕事のいずれかを行うことができます。

Function: make-network-process &rest args

この関数は、ネットワーク接続またはサーバーを作成して、それを表すプロセスオブジェクトをリターンする。引数argsは、キーワード/引数のペアからなるリストである。キーワードの省略は:coding、:filter-multibyte、:reuseaddrを除き、常に値としてnilを指定したのと同じことになる。重要なキーワードを以下に示す(ネットワークオプションに対応するキーワードを、以降のセクションにリストする)。

:name name

プロセス名として、文字列nameを使用する。一意にするために、必要に応じて変更され得る。

:type type

Specify the communication type. A value of nil specifies a stream connection (the default); datagram specifies a datagram connection; seqpacket specifies a sequenced packet stream connection. Both connections and servers can be of these types.

:server server-flag

server-flagが非nilならサーバー、それ以外なら接続を作成する。ストリームタイプのサーバーでは、server-flagはそのサーバーへの保留中の接続キューの長さを指定する、整数を指定できる。キューのデフォルト長は5。

:host host

接続するホストを指定する。hostは、ホスト名またはインターネットアドレスを表す文字列、またはローカルホストを表すシンボルlocalであること。サーバーのときにhostを指定する場合は、有効なローカルホストのアドレスを指定しなければならず、そのアドレスに接続するクライアントだけが受け入れられるだろう。

:service service

service specifies a port number to connect to; or, for a server, the port number to listen on. It should be a service name like ‘"http"’ that translates to a port number, or an integer like ‘80’ or an integer string like ‘"80"’ that specifies the port number directly. For a server, it can also be t, which means to let the system select an unused port number.

:family family

familyは、接続のアドレス(またはプロトコル)のファミリーを指定する。nilは、与えられたhostとserviceにたいして、自動的に適切なアドレスファミリーを決定する。localはUnixのsocketを指定し、この場合hostは無視される。ipv4とipv6はそれぞれ、IPv4とIPv6の使用を指定する。

:use-external-socket use-external-socket

If use-external-socket is non-nil use any sockets passed to Emacs on invocation instead of allocating one. This is used by the Emacs server code to allow on-demand socket activation. If Emacs wasn’t passed a socket, this option is silently ignored.

:local local-address

サーバープロセスでは、local-addressはlistenするアドレスである。これはfamily、host、serviceをオーバーライドするので、これらを指定しないこともできる。

:remote remote-address

接続プロセスでは、remote-addressは接続先のアドレスである。これはfamily、host、serviceをオーバーライドするので、これらを指定しないこともできる。

データグラムサーバーでは、remote-addressはリモートデータグラムアドレスの初期セッティングを指定する。

local-addressとremote-addressのフォーマットは、そのアドレスファミリーに依存する:

- IPv4アドレスは、4つの8ビット整数と1つの16ビット整数からなる5要素のベクター[a b c d p]で表され、それぞれ数値的なIPv4アドレスa.b.c.d、およびポート番号pに対応する。
- IPv6アドレスは、9要素の16ビット整数ベクター[a b c d e f g h p]で表され、それぞれ数値的なIPv６アドレスa:b:c:d:e:f:g:h、およびポート番号pに対応する。
- ローカルアドレスは、ローカルアドレススペース内でアドレスを指定する文字列として表される。
- An unsupported-family address is represented by a cons (f . av), where f is the family number and av is a vector specifying the socket address using one element per address data byte. Do not rely on this format in portable code, as it may depend on implementation defined constants, data sizes, and data structure alignment.

:nowait bool

ストリーム接続にたいしてboolが非nilなら、その接続の完了を待機せずにリターンする。接続が成功または失敗時には、Emacsは"open"(成功時)、または"failed"(失敗時)にマッチするような第2引数により、センチネル関数を呼び出すだろう。デフォルトではwaitせずにblockするので、make-network-processはその接続が成功または失敗するまで、リターンしない。

If you’re setting up an asynchronous TLS connection, you have to also provide the :tls-parameters parameter (see below).

Depending on the capabilities of Emacs, how asynchronous :nowait is may vary. The three elements that may (or may not) be done asynchronously are domain name resolution, socket setup, and (for TLS connections) TLS negotiation.

Many functions that interact with process objects, (for instance, process-datagram-address) rely on them at least having a socket before they can return a useful value. These functions will block until the socket has achieved the desired status. The recommended way of interacting with asynchronous sockets is to place a sentinel on the process, and not try to interact with it before it has changed status to ‘"run"’. That way, none of these functions will block.

:tls-parameters

When opening a TLS connection, this should be where the first element is the TLS type (which should either be gnutls-x509pki or gnutls-anon, and the remaining elements should form a keyword list acceptable for gnutls-boot. (This keyword list can be obtained from the gnutls-boot-parameters function.) The TLS connection will then be negotiated after completing the connection to the host.

:stop stopped

If stopped is non-nil, start the network connection or server in the stopped state.

:buffer buffer

プロセスバッファーとしてbufferを使用する。

:coding coding

このプロセスにたいするコーディングシステムとして、codingを使用する。接続からのデータのデコード、および接続への送信データのエンコードに異なるコーディングシステムを指定するには、codingにたいして(decoding . encoding)と指定する。

このキーワードをまったく指定しないかった場合のデフォルトは、そのデータからコーディングシステムを判断する。

:noquery query-flag

プロセスqueryフラグをquery-flagに初期化する。exit前の問い合わせを参照のこと。

:filter filter

プロセスフィルターをfilterに初期化する。

:filter-multibyte multibyte

multibyteが非nilならマルチバイト文字列、それ以外ならユニバイト文字列がプロセスフィルターに与えられるデフォルトは、enable-multibyte-charactersのデフォルト値である。

:sentinel sentinel

プロセスセンチネルをsentinelに初期化する。

:log log

サーバープロセスのlog関数を、logに初期化する。サーバーがクライアントからネットワーク接続をacceptするたびに、そのlog関数が呼び出される。log関数に渡される引数はserver、connection、messageである。ここでserverはサーバープロセス、connectionはその接続にたいする新たなプロセス、messageは何が発生したかを説明する文字列である。

:plist plist

プロセスplistをplistに初期化する。

実際の接続情報で修正されたオリジナルの引数リストは、process-contactを通じて利用できる。

38.17.2 ネットワークのオプション

以下のネットワークオプションは、ネットワークプロセス作成時に指定できます。:reuseaddrを除き、set-network-process-optionを使用して、これらのオプションを後からセットまたは変更することもできます。

サーバープロセスにたいしては、make-network-processで指定されたオプションはクライアントに継承されないので、子接続が作成されるたびに、必要なオプションをセットする必要があるでしょう。

:bindtodevice device-name

device-nameが空でないネットワークインターフェースを指定する文字列なら、そのインターフェースで受信したパケットだけを処理する。device-nameがnil(デフォルト)なら、任意のインターフェースが受信したパケットを処理する。

このオプションの使用にたいして、特別な特権を要求するシステムがいくつかあるかもしれない。

:broadcast broadcast-flag

データグラムプロセスにたいしてbroadcast-flagが非nilなら、そのプロセスはブロードキャストアドレスに送信されたデータグラムパケットを受信し、ブロードキャストアドレスにパケットを送信できるだろう。これはストリーム接続では無視される。

:dontroute dontroute-flag

dontroute-flagが非nilなら、プロセスはローカルホストと同一ネットワーク上のホストだけに送信することができる。

:keepalive keepalive-flag

ストリーム接続にたいしてkeepalive-flagが非nilなら、低レベルのkeep-aliveメッセージの交換が有効になる。

:linger linger-arg

linger-argが非nilなら、接続を削除(delete-processを参照)する前にキューされたすべてのパケットの送信が成功するまで待機する。linger-argが整数なら、接続クローズ前のキュー済みパケット送信のために待機する、最大の秒数を指定する。デフォルトはnilで、これはプロセス削除時に未送信のキュー済みパケットを破棄することを意味する。

:oobinline oobinline-flag

ストリーム接続にたいしてoobinline-flagが非nilなら、通常のデータストリーム内の帯域外(out-of-band)データを受信し、それ以外なら帯域外データは破棄する。

:priority priority

この接続で送信するパケットの優先順位を、整数priorityにセットする。たとえばこの接続で送信するIPパケットのTOS(type of service)フィールドにセットする等、この数字の解釈はプロトコル固有である。また、そのネットワークインターフェース上で特定の出力キューを選択する等、これにはシステム依存の効果もある。

:reuseaddr reuseaddr-flag

ストリームプロセスサーバーにたいしてreuseaddr-flagが非nil(デフォルト)なら、そのホスト上の別プロセスがそのポートですでにlistenしていなければ、このサーバーは特定のポート番号(:serviceを参照)を再使用できる。reuseaddr-flagがnilなら、(そのホスト上の任意のプロセスが)そのポートを最後に使用した後、そのポート上で新たなサーバーを作成するのが不可能となるような、一定の期間が存在するかもしれない。

Function: set-network-process-option process option value &optional no-error

この関数はネットワークプロセスprocessにたいして、ネットワークオプションのセットまたは変更を行う。指定できるオプションはmake-network-processと同様。no-errorが非nilなら、optionがサポートされないオプションの場合に、この関数はエラーをシグナルせずに、nilをリターンする。この関数が成功裏に完了したら、tをリターンする。

あるオプションのカレントのセッティングは、process-contact関数を通じて利用できる。

38.17.3 ネットワーク機能の可用性のテスト

与えられネットワーク機能が利用可能かテストするためには、以下のようにfeaturepを使用します:

(featurep 'make-network-process '(keyword value))

このフォームの結果は、make-network-process内でkeywordに値valueを指定することが機能するなら、tになります。以下は、この方法でテストできるkeyword/valueペアーのいくつかです。

(:nowait t): 非ブロッキング接続がサポートされていれば非nil。
(:type datagram): データグラムがサポートされていれば非nil。
(:family local): ローカルsocket(別名“UNIX domain”)がサポートされていれば非nil。
(:family ipv6): IPv6がサポートされていれば非nil。
(:service t): サーバーにたいしてシステムがポートを選択できれば非nil。

与えられたネットワークオプションが利用可能かテストするためには、以下のようにfeaturepを使用します:

(featurep 'make-network-process 'keyword)

指定できるkeywordの値は:bindtodevice等です。完全なリストはネットワークのオプションを参照してください。このフォームは、make-network-process(またはset-network-process-option)が特定のネットワークオプションをサポートしていれば、非nilをリターンする。

38.18 その他のネットワーク機能

以下の追加の関数は、ネットワーク接続の作成や操作に有用です。これらは、いくつかのシステムでのみサポートされることに注意してください。

Function: network-interface-list: この関数は、使用しているマシン上のネットワークインターフェースを記述する、リストをリターンする。値は、要素が(name . address)という形式をもつようなalistである。addressは、make-network-processの引数local-addressおよびremote-addressと同じ形式をもつ。

Function: network-interface-info ifname

この関数は、ifnameという名前のネットワークインターフェースに関する情報をリターンする。値は、(addr bcast netmask hwaddr flags)という形式をもつリストである。

addr: インターネットプロトコルアドレス。
bcast: ブロードキャストアドレス。
netmask: ネットワークマスク。
hwaddr: レイヤー2アドレス(たとえばイーサネットMACアドレス)。
flags: そのインターフェースのカレントのフラグ。

Function: format-network-address address &optional omit-port

この関数は、ネットワークアドレスのLisp表現を文字列に変換する。

5要素のベクター[a b c d p]はIPv4アドレスa.b.c.d、およびポート番号pを表す。format-network-addressはこれを、文字列\"a.b.c.d:p\"に変換する。

9要素のベクター[a b c d e f g h p]はポート番号とともに、IPv6アドレスを表す。format-network-addressはこれを、文字列"[a:b:c:d:e:f:g:h]:p"に変換する。

このベクターにポート番号が含まれない、またはomit-portが非nilなら、結果にサフィックス:pは含まれない。

38.19 シリアルポートとの対話

Emacsはシリアルポートと対話できます。インタラクティブな使用、M-x serial-termにたいしては端末ウィンドウをオープンし、Lispプログラムmake-serial-processにたいしてはプロセスオブジェクトを作成します。

シリアルポートは、クローズと再オープンなして、実行時に設定することができます。関数serial-process-configureによりスピード、バイトサイズ、およびその他のパラメーターを変更できます。serial-termで作成された端末ウィンドウでは、モードラインをクリックして設定を行うことができます。

シリアル接続はプロセスオブジェクトとして表され、サブプロセスやネットワークプロセスと同様の方法で使用できます。これによりデータの送受信や、シリアルポートの設定ができます。しかし、シリアルプロセスオブジェクトにプロセスIDはありません。それにたいしてシグナルの送信はできず、ステータスコードは他のタイプのプロセスオブジェクトとは異なります。プロセスオブジェクトへのdelete-process、またはプロセスバッファーにたいするkill-bufferは接続をクローズしますが、そのシリアルポートに接続されたデバイスに影響はありません。

関数process-typeは、シリアルポート接続を表すプロセスオブジェクトにたいする、シンボルserialをリターンします。

シリアルポートはGNU/Linux、Unix、およびMS Windowsのシステムで利用できます。

Command: serial-term port speed

新たなバッファー内で、シリアルポートにたいする端末エミュレーターを開始する。portは、接続先のシリアルポートの名前である。たとえばUnixでは、これは/dev/ttyS0のようになるだろう。MS Windowsでは、COM1や\\.\COM10のようになるかもしれない(Lisp文字列ではバックスラッシュは2重にする)。

speedは、ビット毎秒でのシリアルポートのスピードである。一般的な値は9600。そのバッファーはTermモードになる。このバッファーで使用するコマンドについては、Term Mode in The GNU Emacs Manualを参照のこと。モードラインメニューから、スピードと設定を変更できる。

Function: make-serial-process &rest args

この関数は、プロセスとバッファーを作成する。引数は、キーワード/引数ペアーで指定する。以下は意味のあるキーワードのリストで、最初の2つ(portとspeed)は必須である:

:port port: これは、シリアルポートの名前である。UnixおよびGNUシステムでは/dev/ttyS0のようなファイル名、WindowsではCOM1、COM9より高位のポートでは\\.\COM10のようになるかもしれない(Lisp文字列ではバックスラッシュは2重にする)。
:speed speed: ビット毎秒でのシリアルポートのスピード。この関数はserial-process-configureを呼び出すことにより、スピードを操作する。この関数の更なる詳細については、以降のドキュメントを参照されたい。
:name name: そのプロセスの名前。nameが与えられなければ、portが同様にプロセス名の役目を果たす。
:buffer buffer: そのプロセスに関連付けられたバッファー。値はバッファー、またはそれがバッファーの名前であるような文字列かもしれない。出力を処理するために出力ストリーム、あるいはフィルター関数を指定しなければ、プロセス出力はそのバッファーの終端に出力される。bufferが与えられなければ、そのプロセスバッファーの名前は、:nameキーワードから取得される。
:coding coding: codingは、このプロセスにたいする読み書きに使用される、コーディングシステムを指定する。codingがコンス(decoding . encoding)なら、読み取りにdecoding、書き込みにはencodingが使用される。指定されない場合のデフォルトは、データ自身から判断されるコーディングシステムである。
:noquery query-flag: プロセスqueryフラグを、query-flagに初期化する。exit前の問い合わせを参照のこと。未指定の場合のフラグのデフォルトはnil。
:stop bool: Start process in the stopped state if bool is non-nil. In the stopped state, a serial process does not accept incoming data, but you can send outgoing data. The stopped state is cleared by continue-process and set by stop-process.
:filter filter: プロセスフィルターとして、filterをインストールする。
:sentinel sentinel: プロセスセンチネルとして、sentinelをインストールする。
:plist plist: プロセスの初期plistとして、plistをインストールする。
:bytesize
:parity
:stopbits
:flowcontrol: これらは、make-serial-processが呼び出す、serial-process-configureにより処理される。

後の設定により変更され得るオリジナルの引数リストは、関数process-contactを通じて利用可能。

以下に例を示す:

(make-serial-process :port "/dev/ttyS0" :speed 9600)

Function: serial-process-configure &rest args

この関数は、シリアルポート接続を設定する。引数はキーワード/引数ペアーで指定する。与えられない属性は、そのプロセスのカレントの設定(関数process-contactを通じて利用可能)から再初期化されるか、妥当なデフォルトにセットされる。以下の引数が定義されている:

:process process
:name name
:buffer buffer
:port port: 設定するプロセスを識別するために、これらの引数のいずれかを与えられる。これらの引数が何も与えられなければ、カレントバッファーのプロセスが使用される。
:speed speed: ビット毎秒、別名ボーレート(baud rate)での、シリアルポートのスピード。値には任意の数字が可能だが、ほとんどのシリアルポートは1200から115200の間の数少ない定義済みの値でのみ機能し、もっとも一般的な値は9600である。speedがnilなら、この関数は他のすべての引数を無視して、そのポートを設定しない。これは接続を通じて送信された‘AT’コマンドでのみ設定可能な、Bluetooth/シリアル変換アダプターのような、特殊なシリアルポートで有用かもしれない。speedにたいする値nilは、make-serial-processまたはserial-termの呼び出しにより、すでにオープン済みの接続にたいしてのみ有効である。
:bytesize bytesize: ビット/バイトでの数値で、7か8を指定できる。bytesizeが与えられない、またはnilの場合のデフォルトは8。
:parity parity: 値にはnil(パリティなし)、シンボルodd(奇数パリティ)、シンボルeven(偶数パリティ)を指定できる。parityが与えられない場合のデフォルトはパリティなし。
:stopbits stopbits: 各バイトの送信を終了するために使用されるストップビットの数値。stopbitsには1か2が可能。stopbitsが与えられない、またはnilの場合のデフォルトは1。
:flowcontrol flowcontrol: この接続にたいして使用するフロー制御のタイプで、nil(フロー制御を使用しない)、シンボルhw(RTS/CTSハードウェアフロー制御)、シンボルsw(XON/XOFFソフトウェアフロー制御)のいずれか。flowcontrolが与えられない場合のデフォルトは、フロー制御なし。

シリアルポートの初期設定のために、make-serial-processは内部的にserial-process-configureを呼び出す。

38.20 バイト配列のpackとunpack

このセクションでは、通常はバイナリーのネットワークプロトコル用のバイト配列を、packおよびunpackする朴を説明します。以下の関数は、バイト配列とalistとの間で相互に変換を行います。バイト配列はユニバイト文字列、または整数ベクターとして表現することができます。一方alistはシンボルを固定サイズのオブジェクト、または再帰的な複alistのいずれかに関連付けます。このセクションで参照する関数を使用するためには、bindatライブラリーをロードしてください。

バイト配列からネストされたalistへの変換は、逆方向への変換がシリアライズ化(serializing)、またはpack化(packing)として呼ばれることから、非シリアル化【deserializing)、またはunpack化(unpacking)として知られています。

38.20.1 データレイアウトの記述

To control unpacking and packing, you write a data layout specification, a special nested list describing named and typed fields. This specification controls the length of each field to be processed, and how to pack or unpack it. We normally keep bindat specs in variables whose names end in ‘-bindat-spec’; that kind of name is automatically recognized as risky.

A field’s type describes the size (in bytes) of the object that the field represents and, in the case of multibyte fields, how the bytes are ordered within the field. The two possible orderings are big endian (also known as “network byte ordering”) and little endian. For instance, the number #x23cd (decimal 9165) in big endian would be the two bytes #x23 #xcd; and in little endian, #xcd #x23. Here are the possible type values:

u8
byte: 長さ1の符号なしタイプ。
u16
word
short: 長さ2の、ネットワークバイトオーダーによる符号なし整数。
u24: 長さ3の、ネットワークバイトオーダーによる符号なし整数。
u32
dword
long: 長さ4の、ネットワークバイトオーダーによる符号なし整数。注意: これらの値はEmacsの整数の実装に制限されるだろう。
u16r
u24r
u32r: それぞれ長さ2、3、4のリトルエンディアンオーダーによる符号なし整数。
str len: 長さlenの文字列。
strz len: 長さlenの固定長フィールド内の、NUL終端された文字列。
vec len [type]: タイプtype(デフォルトはbyte)のlen要素のベクター。typeは上述した単純なタイプのいずれか、あるいは(vec len [type])という形式のリストによる別ベクターの指定である。
ip: インターネット」アドレスを表す、4つのbyteのベクター。たとえばlocalhostは[127 0 0 1]。
bits len: lenバイト内のセットされたビット位置のリスト。バイトはビッグエンディアンで、ビット位置は8 * len - 1で始まり0で終わるよう番号が付与される。たとえばbits 2では、#x28 #x1cは(2 3 4 11 13)、#x1c #x28は(3 5 10 11 12)にunpackされる。
(eval form): formは、フィールドがpackまたはunpackされた瞬間に評価されるLisp式。評価した結果は、上記にリストしたタイプ使用のいずれかであること。

固定長フィールドでは長さlenが、フィールド内のバイト数を指定する整数として与えられます。

フィールド長が固定でない場合、通常は先行するフィールドの値に依存します。この場合、長さlenは後述のbindat-get-fieldのフォーマット指定によりフィールド名(field name)を指定するリスト(name ...)、または式(eval form)(formはフィールド長を指定する整数に評価されること)のいずれかで与えることもできます。

フィールド仕様は一般的に([name] handler)という形式をもち、nameはオプションです。紛らわしくなるので、タイプ仕様(上述)やハンドラー仕様(後述)で意味をもつシンボルの名前は使用しないでください。nameはシンボルまたは式(eval form)でもよく、この場合formはシンボルに評価される必要があります。

handlerはそのフィールドがpackまたはunpackされる方法を記述し、以下のいずれかを指定できます:

type

タイプ仕様typeに応じてこのフィールドのunpack/packを行う。

eval form

副作用のためだけにLisp式formを評価する。フィールド名が指定された場合、値はそのフィールド名にバインドされる。

fill len

lenバイトをスキップする。pack化ではそれらを未変更のままとし、通常それらは0のままとなることを意味する。unpack化では、それらが無視されることを意味する。

align len

lenバイトの次の倍数にスキップする。

struct spec-name

副仕様(sub-specification)としてspec-nameを処理する。これは別の構造体内にネストされる構造体を記述する。

union form (tag spec)…

Lisp式formを評価して、それにマッチする最初のtagを探し、それに関連付けられたレイアウト仕様specを処理する。マッチングは以下の3つのいずれかで発生し得る:

tagが(eval expr)という形式をもつ場合、変数tagを動的にformの値にバインドして、exprを評価する。結果が非nilならマッチを示す。
tagがformの値とequalならマッチ。
tagがtなら無条件にマッチ。

repeat count field-specs…

field-specsを順次、再帰的に処理した後、最初のものから繰り返して、すべての仕様全体をcount回処理する。countはフィールド長と同じフォーマットを使用して与えられる。evalフォームが使用された場合は、1回だけ評価される。正しく処理されるには、field-specs内の各仕様は名前を含まなければならない。

bindat仕様内で仕様される(eval form)フォームでは、評価の間にformはこれらの動的にバインドされた変数へのアクセスと更新が可能である。

last: 最後に処理されたフィールドの値。
bindat-raw: バイト配列のデータ。
bindat-idx: unpack化/pack化にたいする、(bindat-rawでの)カレントインデックス。
struct: これまでにunpackされた構造化データ、またはpackされた構造体全体を含むalist。この構造体の特定のフィールドにアクセスするために、bindat-get-fieldを使用できる。
count
index: repeatブロック内部では、これらは(countパラメーターで指定された)繰り返しの最大回数、および(0から数えた)カレント繰り返し回数を含む。countを0にセットすることにより、カレントの繰り返し終了後に、最内繰り返しブロックを終了する。

38.20.2 バイトのunpackとpackのための関数

以降のドキュメントでは、specはデータレイアウト仕様、bindat-rawはバイト配列、structはunpackされたフィールドデータを表すalistを参照します。

Function: bindat-unpack spec bindat-raw &optional bindat-idx

この関数はユニバイト文字列、またはバイト配列bindat-rawのデータを、specに応じてunpackする。これは通常はバイト配列の先頭からunpack化を開始するが、bindat-idxが非nilなら、それはかわりに使用する0基準の開始位置を指定する。

値は、それぞれの要素がunpackされたフィールドを記述する、alistまたはネストされたalist。

Function: bindat-get-field struct &rest name

この関数はネストされたalistであるstructから、フィールドのデータを選択する。structは通常、bindat-unpackがリターンしたもの。nameが単一の引数に対応する場合、それはトップレベルのフィールド値を抽出することを意味する。複数のname引数は、副構造体を繰り返して照合することを指定する。整数の名前は、配列のインデックスとして動作する。

たとえばnameが(a b 2 c)なら、それはフィールドaの副フィールドbの3番目の要素内のフィールドc(Cではstruct.a.b[2].cに相当)を意味する。

packまたはunpackの処理をすることにより、メモリー内でデータ構造が変化しても、そのデータの全フィールド長の合計バイト数である、トータル長(total length)は保たれます。この値は一般的に仕様またはalist単独では、固有ではありません。そのかわり、これら両方の情報が、この計算に役立つのです。同様に、unpackされる文字列や配列の長さは、仕様の記述にしたがい、そのデータのトータル長より長くなるかもしれません。

Function: bindat-length spec struct: この関数はstruct内のデータの、specに応じたトータル長をリターンする。

Function: bindat-pack spec struct &optional bindat-raw bindat-idx

この関数は、alist struct内のデータから、specに応じてpackされたバイト配列をリターンする。これは通常、先頭から充填された、新たなバイト配列を作成する。しかしbindat-rawが非nilなら、それはpack先として事前に割り当てられたユニバイト文字列、またはベクターを指定する。bindat-idxが非nilなら、それはbindat-rawへpackする開始オフセットを指定する。

事前に割り当てる際には、out-of-rangeエラーを避けるために、(length bindat-raw)がトータル長またはそれ以上であることを確認すること。

Function: bindat-ip-to-string ip

インターネットアドレスのベクターipを、通常のドット表記による文字列に変換する。

(bindat-ip-to-string [127 0 0 1])
     ⇒ "127.0.0.1"

38.20.3 バイトのunpackとpackの例

Here are two complete examples that use bindat.el. The first shows simple byte packing:

(require 'bindat)

(defun rfc868-payload ()
  (bindat-pack
   '((now-hi u16)
     (now-lo u16))
   ;; Emacs uses Unix epoch, while RFC868 epoch
   ;; is 1900-01-01 00:00:00, which is 2208988800
   ;; (or #x83aa7e80) seconds more.
   (let ((now (time-add nil '(#x83aa #x7e80))))
     `((now-hi . ,(car now))
       (now-lo . ,(cadr now))))))

(let ((s (rfc868-payload)))
  (list (multibyte-string-p s)
        (mapconcat (lambda (byte)
                     (format "%02x" byte))
                   s " ")
        (current-time-string)))
     ⇒ (nil "dc 6d 17 01" "Fri Mar 10 13:13:53 2017")

以下は複雑な構造体を定義してunpackする例です。以下のようなCの構造体があるものとします:

struct header {
    unsigned long    dest_ip;
    unsigned long    src_ip;
    unsigned short   dest_port;
    unsigned short   src_port;
};

struct data {
    unsigned char    type;
    unsigned char    opcode;
    unsigned short   length;  /* ネットワークバイトオーダー */
    unsigned char    id[8];   /* NUL終端文字列 */
    unsigned char    data[/* (length + 3) & ~3 */];
};

struct packet {
    struct header    header;
    unsigned long    counters[2];  /* リトルエンディアンオーダー */
    unsigned char    items;
    unsigned char    filler[3];
    struct data      item[/* items */];

};

対応するデータレイアウト仕様が以下です:

(setq header-spec
      '((dest-ip   ip)
        (src-ip    ip)
        (dest-port u16)
        (src-port  u16)))

(setq data-spec
      '((type      u8)
        (opcode    u8)
        (length    u16)  ; ネットワークバイトオーダー
        (id        strz 8)
        (data      vec (length))
        (align     4)))

(setq packet-spec
      '((header    struct header-spec)
        (counters  vec 2 u32r)   ; リトルエンディアンオーダー
        (items     u8)
        (fill      3)
        (item      repeat (items)
                   (struct data-spec))))

バイナリーデータによる表現は:

(setq binary-data
      [ 192 168 1 100 192 168 1 101 01 28 21 32
        160 134 1 0 5 1 0 0 2 0 0 0
        2 3 0 5 ?A ?B ?C ?D ?E ?F 0 0 1 2 3 4 5 0 0 0
        1 4 0 7 ?B ?C ?D ?E ?F ?G 0 0 6 7 8 9 10 11 12 0 ])

対応するデコードされた構造体は:

(setq decoded (bindat-unpack packet-spec binary-data))
     ⇒
((header
  (dest-ip   . [192 168 1 100])
  (src-ip    . [192 168 1 101])
  (dest-port . 284)
  (src-port  . 5408))
 (counters . [100000 261])
 (items . 2)
 (item ((data . [1 2 3 4 5])
        (id . "ABCDEF")
        (length . 5)
        (opcode . 3)
        (type . 2))
       ((data . [6 7 8 9 10 11 12])
        (id . "BCDEFG")
        (length . 7)
        (opcode . 4)
        (type . 1))))

以下はこの構造体からデータを取得する例です:

(bindat-get-field decoded 'item 1 'id)
     ⇒ "BCDEFG"

39 Emacsのディスプレー表示

このチャプターでは、Emacsによるユーザーへのプレゼンテーションである、表示に関連する機能のいくつかを説明します。

39.1 スクリーンのリフレッシュ		スクリーン上にあるすべてのもののクリアーと再描画。
39.2 強制的な再表示		再描画の強制。
39.3 切り詰め		長いテキストの折り畳みと折り返し。
39.4 エコーエリア		スクリーン最下部へのメッセージ表示。
39.5 警告のレポート		ユーザーへの警告メッセージの表示。
39.6 不可視のテキスト		バッファーのテキストの一部を隠す。
39.7 選択的な表示		バッファーのテキストの一部を隠す(旧来の方式)。
39.8 一時的な表示		自動的に消える表示。
39.9 オーバーレイ		オーバーレイを使用したバッファーの一部のハイライト。
39.10 表示されるテキストのサイズ		表示されたテキストの大きさ。
39.11 行の高さ		行の高さの制御。
39.12 フェイス		テキスト文字のグラフィカルスタイル(フォント、カラー等)を定義するフェイス。
39.13 フリンジ		ウィンドウフリンジの制御。
39.14 スクロールバー		Controlling scroll bars.
39.15 ウィンドウディバイダー		ウィンドウを視覚的に区別する。
39.16 `display`プロパティ		特別な表示機能の有効化。
39.17 イメージ		Emacsバッファー内でのイメージ表示。
39.18 Embedded Native Widgets		Displaying native widgets in Emacs buffers.
39.19 ボタン		Emacsバッファー内へのイメージ表示クリック可能ボタン追加。
39.20 抽象的なディスプレー		オブジェクトコレクション用のEmacsウィジェット。
39.21 カッコの点滅		Emacsがマッチする開カッコを表示する方法。
39.22 文字の表示		Emacsがマッチする個々の文字を表示する方法。
39.23 ビープ		ユーザーへの可聴シグナル。
39.24 ウィンドウシステム		どのウィンドウシステムが使用されているか。
39.25 Tooltips		Tooltip display in Emacs.
39.26 双方向テキストの表示		アラビア語やペルシア語のような、双方向スクリプトの表示。

39.1 スクリーンのリフレッシュ

関数redraw-frameは、与えられたフレーム(フレームを参照)のコンテンツ全体にたいして、クリアーおよび再描画を行います。これはスクリーンが壊れている(corrupted)場合に有用です。

Function: redraw-frame &optional frame: This function clears and redisplays frame frame. If frame is omitted or nil, it redraws the selected frame.

更に強力なのがredraw-displayです:

Command: redraw-display: この関数は、すべての可視なフレームのクリアーと再描画を行う。

Emacsでは、ユーザー入力は再描画より優先されます。入力が可能なときにこれらの関数を呼び出すと、これらはすぐに再描画はしませんが、要求された再描画はやがて、すべての入力処理後に行われます。

テキスト端末では、Emacsのサスペントと再開により、通常はスクリーンのリフレッシュも行われます。Emacsのようなディスプレイ指向のプログラムと、通常のシーケンシャル表示のプログラムで、コンテンツを区別して記録する端末エミュレーターがいくつかあります。そのような端末を使用する場合は、おそらく再開時の再表示を抑制したいでしょう。

User Option: no-redraw-on-reenter: この変数は、Emacsがサスペンドおよび再開された後に、スクリーン全体を再描画するかどうかを制御する。非nilなら再描画は不要、nilなら再描画が必要であることを意味する。デフォルトはnil。

39.2 強制的な再表示

Emacsは入力の待機時は常に、再表示を試みます。以下の関数により、実際に入力を待機することなく、Lispコードの中から、即座に再表示を試みることを要求できます。

Function: redisplay &optional force

この関数は、即座に再表示を試みる。オプション引数forceが非nilなら、入力が保留中に横取りされるかわりに、強制的に再表示が行われる。

この関数は実際に再表示が試行されたならt、それ以外はnilをリターンする。tという値は、再表示の試行が完了したことを意味しない。新たに到着した入力に横取りされた可能性がある。

redisplayが即座に再表示を試みたとしても、Emacsがフレーム(複数可)のどの部分を再表示するか決定する方法を変更するわけではありません。それとは対照的に、以下の関数は特定のウィンドウを(あたかもコンテンツが完全に変更されたかのように)、保留中の再表示処理に追加します。しかし再描画を即座には試みません。

Function: force-window-update &optional object

この関数は、Emacsが次に再表示を行う際にいくつか、あるいはすべてのウィンドウが更新されるよう強制する。objectがウィンドウならそのウィンドウ、バッファーまたはバッファー名ならそのバッファーを表示するすべてのウィンドウ、nil(または省略)の場合はすべてのウィンドウが更新される。

この関数は、即座に再表示を行わない。再表示はEmacsが入力を待機時、または関数redisplay呼び出し時に行われる。

Variable: pre-redisplay-function: A function run just before redisplay. It is called with one argument, the set of windows to be redisplayed. The set can be nil, meaning only the selected window, or t, meaning all the windows.

Variable: pre-redisplay-functions: This hook is run just before redisplay. It is called once in each window that is about to be redisplayed, with current-buffer set to the buffer displayed in that window.

39.3 切り詰め

When a line of text extends beyond the right edge of a window, Emacs can continue the line (make it wrap to the next screen line), or truncate the line (limit it to one screen line). The additional screen lines used to display a long text line are called continuation lines. Continuation is not the same as filling; continuation happens on the screen only, not in the buffer contents, and it breaks a line precisely at the right margin, not at a word boundary. See section fill.

On a graphical display, tiny arrow images in the window fringes indicate truncated and continued lines (see section フリンジ). On a text terminal, a ‘$’ in the rightmost column of the window indicates truncation; a ‘\’ on the rightmost column indicates a line that wraps. (The display table can specify alternate characters to use for this; see section ディスプレーテーブル).

User Option: truncate-lines: このバッファーローカル変数が非nilなら、ウィンドウ右端を超過する行は切り詰められ、それ以外なら継続される。特別な例外として、部分幅(partial-width)ウィンドウ(フレーム全体の幅を占有しないウィンドウ)では、変数truncate-partial-width-windowsが優先される。

User Option: truncate-partial-width-windows: この変数は、部分幅(partial-width)ウィンドウ内の、行の切り詰めを制御する。部分幅ウィンドウとは、フレーム全体の幅を占有しないウィンドウである(ウィンドウの分割を参照)。値がnilなら、行の切り詰めは変数truncate-lines(上記参照)により決定される。値が整数nの場合は、部分幅ウィンドウの列数がnより小さければ、truncate-linesの値とは無関係に行は切り詰められ、部分幅ウィンドウの列数がn以上なら、行の切り詰めはtruncate-linesにより決定される。それ以外の非nil値では、truncate-linesの値とは無関係にすべての部分幅ウィンドウで行は切り詰められる。

ウィンドウ内で水平スクロール(水平スクロールを参照)を使用中は、切り詰めが強制されます。

Variable: wrap-prefix

このバッファーローカル変数が非nilなら、それはEmacsが各継続行の先頭に表示する、折り返しプレフィックス(wrap prefix)を定義する(行を切り詰めている場合、wrap-prefixは使用されない)。この値は文字列、イメージ(その他のディスプレー仕様を参照)、またはディスプレイプロパティ:widthや:align-toで指定されるような、伸長された空白文字を指定できる(スペースの指定を参照)。値はテキストプロパティdisplayと同じ方法で解釈される。displayプロパティを参照のこと。

折り返しプレフィックスは、テキストプロパティまたはオーバーレイプロパティwrap-prefixを使用することにより、テキストのリージョンにたいして指定することもできる。これはwrap-prefix変数より優先される。特殊な意味をもつプロパティを参照のこと。

Variable: line-prefix

このバッファーローカル変数が非nilなら、それはEmacsがすべての非継続行の先頭に表示する、行プレフィックス(line prefix)を定義する。この値は文字列、イメージ(その他のディスプレー仕様を参照)、またはディスプレイプロパティ:widthや:align-toで指定されるような、伸長された空白文字を指定できる(スペースの指定を参照)。値はテキストプロパティdisplayと同じ方法で解釈される。displayプロパティを参照のこと。

行プレフィックスは、テキストプロパティまたはオーバーレイプロパティline-prefixを使用することにより、テキストのリージョンにたいして指定することもできる。これはline-prefix変数より優先される。特殊な意味をもつプロパティを参照のこと。

39.4 エコーエリア

エコーエリア(echo area)はエラーメッセージ(エラー)や、messageプリミティブで作成されたメッセージの表示、およびキーストロークをエコーするために使用されます。(アクティブ時には)ミニバッファーがスクリーン上のエコーエリアと同じ場所に表示されるという事実にも関わらず、エコーエリアはミニバッファーと同じではありません。The Minibuffer in The GNU Emacs Manualを参照してください。

このセクションに記述された関数とは別に、出力ストリームとしてtを指定することにより、エコーエリアにLispオブジェクトをプリントできます。出力ストリームを参照してください。

39.4.1 エコーエリアへのメッセージの表示

このセクションでは、エコーエリア内にメッセージを表示する、標準的な関数を説明します。

Function: message format-string &rest arguments

This function displays a message in the echo area. format-string is a format string, and arguments are the objects for its format specifications, like in the format-message function (see section 文字列のフォーマット). The resulting formatted string is displayed in the echo area; if it contains face text properties, it is displayed with the specified faces (see section フェイス). The string is also added to the *Messages* buffer, but without text properties (see section *Messages*へのメッセージのロギング).

バッチモードでは、後に改行が付加されたメッセージが、標準エラーストリームにプリントされる。

When inhibit-message is non-nil, no message will be displayed in the echo area, it will only be logged to ‘*Messages*’.

format-stringがnilか空文字列なら、messageはエコーエリアをクリアーする。エコーエリアが自動的に拡張されていたら、これにより通常のサイズに復元される。ミニバッファーがアクティブなら、これによりスクリーン上に即座にミニバッファーのコンテンツが復元される。

(message "Reverting `%s'..." (buffer-name))
 -| Reverting ‘subr.el’...
⇒ "Reverting ‘subr.el’..."

---------- Echo Area ----------
Reverting ‘subr.el’...
---------- Echo Area ----------

エコーエリアやポップバッファー内に、自動的にメッセージを表示するには、そのサイズに応じてdisplay-message-or-buffer(以下参照)を使用する。

Warning: If you want to use your own string as a message verbatim, don’t just write (message string). If string contains ‘%’, ‘`’, or ‘'’ it may be reformatted, with undesirable results. Instead, use (message "%s" string).

Variable: inhibit-message: When this variable is non-nil, message and related functions will not use the Echo Area to display messages.

Macro: with-temp-message message &rest body: この構成はbody実行の間、エコーエリア内にメッセージを一時的に表示する。これはmessageを表示してbodyを実行し、それからエコーエリアの前のコンテンツをリストアするとともに、bodyの最後のフォームの値をリターンする。

Function: message-or-box format-string &rest arguments

この関数はmessageと同様にメッセージを表示するが、エコーエリアではなくダイアログボックスにメッセージを表示するかもしれない。この関数があるコマンド内からマウスを使用して呼び出された場合 — より正確にはlast-nonmenu-event(コマンドループからの情報を参照)がnilかリストなら、そのメッセージの表示にダイアログボックスまたはポップアップメニューを使用する。それ以外の場合は、エコーエリアを使用する(これはy-or-n-pが同様の決定を行う際に使用する条件と同じである。Yes-or-Noによる問い合わせを参照されたい)。

呼び出しの前後でlast-nonmenu-eventを適切な値にバインドすることにより、エコーエリアでのマウスの使用を強制できる。

Function: message-box format-string &rest arguments: この関数はmessageと同様にメッセージを表示するが、利用可能なら常にダイアログボックス(かポップアップメニュー)を使用する。端末がサポートしないために、ダイアログボックスまたはポップアップメニューが使用できなければ、message-boxはmessageと同様にエコーエリアを使用する。

Function: display-message-or-buffer message &optional buffer-name action frame

この関数はメッセージmessageを表示する。messageは文字列かバッファーを指定できる。これがmax-mini-window-heightで定義されるエコーエリアの最大高さより小さければ、messageを使用してエコーエリアに表示される。それ以外なら、メッセージを表示するためにdisplay-bufferはポップアップバッファーを使用する。

エコーエリアに表示したメッセージ、またはポップアップバッファー使用時はその表示に使用したウィンドウをリターンする。

messageが文字列なら、オプション引数buffer-nameはポップアップバッファー使用時にメッセージ表示に使用するバッファー名(デフォルトは*Message*)である。messageが文字列でエコーエリアに表示されてる場合は、いずれにせよコンテンツをバッファーに挿入するかどうかは指定されない。

The optional arguments action and frame are as for display-buffer, and only used if a buffer is displayed.

Function: current-message: この関数は、エコーエリア内にカレントで表示されているメッセージ、またはそれが存在しなければnilをリターンする。

39.4.2 処理の進捗レポート

処理の完了まで暫く時間を要するかもしれない際は、その進行状況についてユーザーに通知するべきです。これによりユーザーが残り時間を予測するとともに、Emacsがhungしているのではなく、処理中であえうことが明確に確認できます。プログレスリポーター(progress reporter: 進行状況リポーター)を使用するのが、これを行う便利な方法です。

以下は、何も有用なことを行わない、実行可能な例です:

(let ((progress-reporter
       (make-progress-reporter "Collecting mana for Emacs..."
                               0  500)))
  (dotimes (k 500)
    (sit-for 0.01)
    (progress-reporter-update progress-reporter k))
  (progress-reporter-done progress-reporter))

Function: make-progress-reporter message &optional min-value max-value current-value min-change min-time

この関数は、以下に挙げる他の関数として使用されるであろう、プログレスリポーターオブジェクトを作成して、リターンする。これはプログレスリポーターを高速にするように、可能なかぎり多くのデータを事前に計算するというアイデアが元である。

When this progress reporter is subsequently used, it will display message in the echo area, followed by progress percentage. message is treated as a simple string. If you need it to depend on a filename, for instance, use format-message before calling this function.

The arguments min-value and max-value should be numbers standing for the starting and final states of the operation. For instance, an operation that scans a buffer should set these to the results of point-min and point-max correspondingly. max-value should be greater than min-value.

かわりに、min-valueとmax-valueをnilにセットすることができる。この場合、プログレスリポーターは進行状況のパーセンテージを報告しない。かわりにプログレスリポーターを更新するたびに刻み(notch)を回転する“スピナー(spinner)”を表示する。

min-valueとmax-valueが数値なら、進行状況の初期の数値を与える引数current-valueを与えることができる。省略時のデフォルトはmin-value。

残りの引数は、エコーエリアの更新レートを制御する。プログレスリポーターは次のメッセージを表示する前に、その処理が少なくともmin-changeパーセントより多く完了するまで待機する。デフォルトは1パーセント。min-timeは連続するプリントの間に空ける最小時間をミリ秒単位で指定する(いくつかのオペレーティングシステムでは、プログレスリポーターは秒の少数部をさまざまな制度で処理するかもしれない)。

この関数はprogress-reporter-updateを呼び出すた、最初のメッセージは即座にプリントされる。

Function: progress-reporter-update reporter &optional value

この関数は、操作の進行状況報告に関する、主要な機能を担う。これはreporterのメッセージと、その後にvalueにより決定された進行状況のパーセンテージを表示する。パーセンテージが0、または引数min-changeとmin-timeに比べて十分0に近ければ、出力は省略される。

reporterは、make-progress-reporter呼び出しがリターンした結果でなければならない。valueは処理のカレント状況を指定し、make-progress-reporterに渡されたmin-valueとmax-valueの間(両端を含む)でなければならない。たとえばバッファーのスキャンにおいては、valueはpointび呼び出し結果であるべきだろう。

この関数はmake-progress-reporterに渡されたmin-changeとmin-timeにしたがい、毎回の呼び出しで新たなメッセージを出力しない。したがってこれは非常に高速であり、通常はこれを呼び出す回数を減らすことを試みるべきではない。結果として生じるオーバーヘッドは、あなたの努力をほぼ否定するだろう。

Function: progress-reporter-force-update reporter &optional value new-message

この関数はprogress-reporter-updateと同様だが、これは無条件にメッセージをエコーエリアにプリントする点が異なる。

最初の2つの引数は、progress-reporter-updateの場合と同じ意味をもつ。オプションのnew-messageで、reporterのメッセージを変更できる。この関数は常にエコーエリアを更新するので、そのような変更は即座にユーザーに示されるだろう。

Function: progress-reporter-done reporter

This function should be called when the operation is finished. It prints the message of reporter followed by word ‘done’ in the echo area.

You should always call this function and not hope for progress-reporter-update to print ‘100%’. Firstly, it may never print it, there are many good reasons for this not to happen. Secondly, ‘done’ is more explicit.

Macro: dotimes-with-progress-reporter (var count [result]) message body…

これはdotimesと同じ方法で機能するが、上述の関数を使用してループ進行状況(loop progress)の報告も行う、便利なマクロである。これにより、タイプ量を幾分節約できる。

以下の方法でこのマクロを使用することにより、このセクション冒頭の例を書き換えることができる:

(dotimes-with-progress-reporter
    (k 500)
    "Collecting some mana for Emacs..."
  (sit-for 0.01))

39.4.3 `Messages`へのメッセージのロギング

エコーエリア内に表示されるほとんどすべてのメッセージは、ユーザーが後で参照できるように、*Messages*バッファー内にも記録されます。これにはmessageにより出力されたメッセージも含まれます。デフォルトではこのバッファーは読み取り専用で、メジャーモードmessages-buffer-modeを使用します。ユーザーによる*Messages*バッファーのkillを妨げるものは何もありませんが、次回のメッセージ表示でバッファーは再作成されます。*Messages*バッファーに直接アクセスする必要があり、それが確実に存在するようにしたいLispコードはすべて、関数messages-bufferを使用するべきです。

Function: messages-buffer: この関数は、*Messages*バッファーをリターンする。バッファーが存在しなければ作成して、そのバッファーをmessages-buffer-modeに切り替える。

User Option: message-log-max

この変数は、*Messages*バッファー内に保持するべき行数を指定する。値tは保持すべき行数に制限がないことを意味し、値nilはメッセージのロギングを完全に無効にする。以下は、メッセージを表示して、それがロギングされることを防ぐ例である:

(let (message-log-max)
  (message …))

*Messages*にたいするユーザーの利便性を向上させるために、ロギング機能は連続する同じメッセージを結合します。さらに、2つのケースのために連続する関連メッセージの結合も行います。2つのケースとは、応答を後にともなう質問(question followed by answer)と、一連のプログレスメッセージ(series of progress messages)です。

A question followed by an answer has two messages like the ones produced by y-or-n-p: the first is ‘question’, and the second is ‘question...answer’. The first message conveys no additional information beyond what’s in the second, so logging the second message discards the first from the log.

A series of progress messages has successive messages like those produced by make-progress-reporter. They have the form ‘base...how-far’, where base is the same each time, while how-far varies. Logging each message in the series discards the previous one, provided they are consecutive.

関数make-progress-reporterおよびy-or-n-pは、メッセージログ結合機能をアクティブにするために、何ら特別なことを行う必要はありません。これは‘...’で終わる共通のプレフィックスを共有する、連続する2つのメッセージをログする際は、常にこの処理を行います。

39.4.4 エコーエリアのカスタマイズ

以下の変数は、エコーエリアが機能する方法の詳細を制御します。

Variable: cursor-in-echo-area

この変数は、エコーエリア内にメッセージ表示時に、カーソルを表示する場所を制御する。これが非nilなら、カーソルはメッセージの終端に表示される。それ以外なら、カーソルはエコーエリア内ではなく、ポイント位置に表示される。

この値は、通常はnilである。Lispプログラムは短時間の間、これをtにバインドする。

Variable: echo-area-clear-hook: このノーマルフックは(message nil)、または別の何らかの理由によりエコーエリアが作成されると、常に実行される。

User Option: echo-keystrokes

この変数は、コマンド文字をエコーする前に、どれだけの時間を待機するかを決定する。この値は数字でなければならず、エコー前に待機する秒数を指定する。ユーザーが(C-xのような)プレフィックスキーをタイプしてから、継続してタイプを継続するのをこの秒数遅延した場合、エコーエリア内にそのプレフィックスキーがエコーされる(あるキーシーケンスで一度エコーが開始されると、同一のキーシーケンス内の後続するすべての文字は、即座にエコーされる)。

値が0なら、コマンド入力はエコーされない。

Variable: message-truncate-lines: 通常、長いメッセージの表示により、そのメッセージ全体を表示するために、エコーエリアはリサイズされる。しかし変数message-truncate-linesが非nilなら、エコーエリアをリサイズせず、エコーエリアに収まるようメッセージは切り詰められる。

The variable max-mini-window-height, which specifies the maximum height for resizing minibuffer windows, also applies to the echo area (which is really a special use of the minibuffer window; see section ミニバッファーのウィンドウ).

39.5 警告のレポート

警告(warnings)とは、プログラムがユーザーにたいして問題の可能性を知らせるが、実行は継続するための機能です。

39.5.1 警告の基礎

すべての警告は、ユーザーに問題を説明するためのテキストのメッセージと、重大レベル(severity level)をもっています。重大レベルはシンボルです。以下は可能性のある重大レベルとその意味を、重大度の降順でリストしたものです:

:emergency: 直ちに対処しなければ、Emacs処理が間もなく深刻に害される問題。
:error: 本質的に悪いデータまたは状況のリポート。
:warning: 本質的に悪くはないが、可能性のある問題を励起する恐れのあるデータまたは状況のリポート。
:debug: デバッグ中なら有用かもしれない情報のリポート。

あなたのプログラムが無効な入力データに遭遇した際には、error呼び出しによるLispエラーのシグナルするか、または重大度:errorの警告をリポートすることができます。Lispエラーのシグナルはもっとも簡単に行えることですが、それはプログラムが処理を継続できないことを意味します。間違ったデータでも処理を継続するための方法を実装するために、そのトラブルを受け取めたい場合には、その問題をユーザーに知らせるために、重大度:errorの警告をリポートするのが正しい方法です。たとえばEmacs Lispバイトコンパイラーはこの方法によりエラーを報告して、他の関数のコンパイルを継続できます(プログラムがLispエラーをシグナルして、それをcondition-caseでhandleしたなら、ユーザーがそのエラーを確認することはないだろう。これは警告としてリポートすることにより、ユーザーにメッセージを示すことができる)。

クラス分けのために、それぞれの警告には警告タイプ(warning type)があります。このタイプはシンボルのリストです。最初のシンボルは、そのプログラムのユーザーオプションとして使用する、カスタムグループであるべきです。たとえばバイトコンパイラーの警告は、警告タイプ(bytecomp)を使用します。もし望むなら、このリスト内で更にシンボルを使用することにより、警告をサブカテゴリー化することもできます。

Function: display-warning type message &optional level buffer-name

この関数はメッセージとしてmessage、警告タイプとしてtypeを使用して、警告をリポートする。levelは重大レベルであること。デフォルトは:warning。

buffer-nameが非nilなら、それは警告をロギングするためのバッファー名を指定する。デフォルトは*Warnings*。

Function: lwarn type level message &rest args: This function reports a warning using the value of (format-message message args...) as the message in the *Warnings* buffer. In other respects it is equivalent to display-warning.

Function: warn message &rest args: This function reports a warning using the value of (format-message message args...) as the message, (emacs) as the type, and :warning as the severity level. It exists for compatibility only; we recommend not using it, because you should specify a specific warning type.

39.5.2 警告のための変数

プログラムは、このセクション内で説明する変数をバインドすることにより、警告が表示される方法をカスタマイズできます。

Variable: warning-levels

このリストは、警告の重大レベルの意味と、重大度の順序を定義する。それぞれの要素は1つの重大レベルを定義し、それらは重大度の降順で配置される。

各要素は(level string function)という形式をもち、levelはその要素が定義する重大レベルである。stringはそのレベルのテキストによる説明である。stringは警告タイプ情報の配置箇所の指定に‘%s’を使用するか、さもなくばその情報を含まぬよう‘%s’を省略できる。

オプションのfunctionが非nilなら、これはユーザーの注目を得るために引数なしで呼び出される関数であること。

通常は、この変数の値を変更するべきではない。

Variable: warning-prefix-function

値が非nilなら、それは警告用にプレフィックスを生成する関数であること。プログラムは、この変数を適切な関数にバインドできる。display-warningはwarningsバッファーがカレントの状態でこの関数を呼び出し、関数はそのバッファーにテキストを挿入できる。そのテキストが、警告メッセージの先頭になる。

この関数は重大レベル、およびwarning-levels内でのその重大レベルのエントリーという、2つの引数で呼び出される。これは、エントリーとして使用するためのリストをリターンするべきである(この値はwarning-levelsの実際のメンバーである必要はない)。この値を構築することにより、関数はその警告の重大レベルを変更したり、与えられた重大レベルにたいして異なる処理を指定することができる。

この変数の値がnilなら、呼び出される関数は存在しない。

Variable: warning-series

プログラムは、次の警告がシリーズの開始であることを告げるために、この変数をtにバインドできる。複数の警告がシリーズを形成するということは、それぞれの警告にたいしてポイントが維持されるよう移動して、最後の警告にポイントが表示されるのではなく、そのシリーズの最初の警告にポイントを残すことを意味する。このシリーズは、そのローカルバインドが非バインドされて、warning-seriesが再びnilになったときに終了する。

この値は、関数定義をもつシンボルでもよい。これは、次の警告によりwarningsバッファーがカレントの状態で、引数なしでその関数が呼び出されることを除き、tと等価である。この関数は、その警告シリーズのヘッダーの役目をもつであろうテキストを挿入できる。

あるシリーズが開始されると、その値はwarningsバッファー内でシリーズ開始となるバッファー位置を指すマーカーとなる。

この変数の通常の値はnilで、これはそれぞれの警告を個別に処理することを意味する。

Variable: warning-fill-prefix: この変数が非nilなら、それは各警告テキストのフィルに使用する、フィルプレフィックスを指定する。

Variable: warning-type-format: この変数は、警告メッセージ内の警告タイプを表示するための、フォーマットを指定する。この方法でフォーマットされたタイプは、warning-levels内のエントリー内の文字列制御下にあるメッセージに含まれることになる。デフォルト値は" (%s)"。これを""にバインドすると、警告タイプはまったく表示されなくなる。

39.5.3 警告のためのオプション

以下の変数は、何が発生したときにLispプログラムが警告をリポートするかを、ユーザーが制御するために使用されます。

User Option: warning-minimum-level: このユーザーオプションは、ユーザーにたいして即座に表示されるべき、最小の重大レベルを指定する。デフォルトは:warningで、これは:debug警告を除くすべての警告が即座に表示されることを意味する。

User Option: warning-minimum-log-level: このユーザーオプションは、warningsバッファー内にログされるべき、最小の重大レベルを指定する。デフォルトは:warningで、これは:debug警告を除くすべての警告がログされることを意味する。

User Option: warning-suppress-types: このリストは、ユーザーにたいしてどの警告タイプを即座に表示するべきではないかを指定する。このリスト内の各要素は、シンボルのリストであること。それの要素が警告タイプ内の最初の要素にマッチしたら、その警告は即座に表示されない。

User Option: warning-suppress-log-types: このリストは、ユーザーにたいしてどの警告タイプがwarningsバッファーにログされるべきではないかを指定する。このリスト内の各要素は、シンボルのリストであること。それの要素が警告タイプ内の最初の数要素にマッチしたら、その警告はログされない。

39.5.4 遅延された警告

コマンド実行中には警告の表示を避けて、コマンドの終わりでのみ警告を表示したいことがあるかもしれません。これは、変数delayed-warnings-listにより行うことができます。

Variable: delayed-warnings-list

この変数の値は、カレントのコマンド完了後に表示される警告のリストである。各要素は以下のようなリストでなければならない:

(type message [level [buffer-name]])

これらは、はdisplay-warningの引数リストと同じ形式、同じ意味である(警告の基礎を参照)。post-command-hook(コマンドループの概要を参照)の実行直後、Emacsのコマンドループはこの変数で指定されたすべての警告を表示してから、変数をnilにリセットする。

遅延警告メカニズムをよりカスタマイズする必要があるプログラムは、変数delayed-warnings-hookを変更することができます:

Variable: delayed-warnings-hook

This is a normal hook which is run by the Emacs command loop, after post-command-hook, in order to process and display delayed warnings.

デフォルト値は、2つの関数からなるリストである:

(collapse-delayed-warnings display-delayed-warnings)

関数collapse-delayed-warningsは、delayed-warnings-listから重複するエントリーを削除する。関数display-delayed-warningsは、delayed-warnings-list内の各要素にたいして順次display-warningを呼び出してから、delayed-warnings-listをnilにセットする。

39.6 不可視のテキスト

invisibleプロパティにより、スクリーン上に表示されないように、文字を不可視(invisible)にすることができます。これはテキストプロパティ(テキストのプロパティを参照)、またはオーバーレイプロパティ(オーバーレイを参照)のいずれかで行うことができます。カーソル移動も、これらの文字を部分的に無視します。あるコマンドの後に、不可視テキスト範囲内にポイントがあることをコマンドループが検知した場合、コマンドループはポイントをそのテキストの別サイドへ再配置します。

もっともシンプルなケースでは、非nilのinvisibleプロパティにより、文字は不可視になります。これがデフォルトのケースであり、もしbuffer-invisibility-specのデフォルト値を変更したくない場合は、これがinvisibleプロパティを機能させる方法です。自身でbuffer-invisibility-specをセットする予定がなければ、invisibleプロパティの値として、通常はtを使用するべきです。

より一般的には、どのinvisibleの値がテキストを不可視にするかを制御するために、変数buffer-invisibility-specを使用できます。テキストにたいして異なるinvisibleの値を与えることにより、事前に別のサブセットへテキストをクラス分けした後に、buffer-invisibility-specの値を変更して、さまざまなサブセットを可視または不可視にすることができます。

特にデータベース内のエントリーのリストを表示するプログラム内では、buffer-invisibility-specによる可視性の制御は有用です。これにより、データベース内の一部だけを閲覧するフィルターコマンドを、簡便に実装することが可能になります。この変数をセットするのは非常に高速で、バッファー内のすべてのテキストにたいしてプロパティが変更されたかスキャンするより、はるかに高速です。

Variable: buffer-invisibility-spec

この変数は、どの種類のinvisibleプロパティが、実際に文字を不可視にするかを指定する。この変数はセットすることにより、バッファーローカルになる。

t

invisibleプロパティが非nilなら、その文字は不可視になる。これがデフォルトである。

リスト

このリスト内の各要素は、不可視性の条件を指定する。ある文字のinvisibleプロパティがこれらの条件のいずれかに適合したら、その文字は不可視になる。このリストは2種類の要素をもつことができる:

atom: invisibleプロパティの値がatom、またはatomをメンバーにもつリストなら、その文字は不可視になる。比較はeqにより行われる。
(atom . t): invisibleプロパティの値がatom、またはatomをメンバーにもつリストなら、その文字は不可視になる。比較はeqにより行われる。さらに、そのような文字シーケンスは省略記号(ellipsis)として表示される。

特にbuffer-invisibility-specへの要素の追加と削除のために、2つの関数が提供されています。

Function: add-to-invisibility-spec element: この関数は、buffer-invisibility-specに要素elementを追加する。buffer-invisibility-specがtなら、これはリスト(t)に変更され、invisibleプロパティがtのテキストは不可視のまま留まる。

Function: remove-from-invisibility-spec element: この関数は、buffer-invisibility-specから要素elementを削除する。リスト内にelementがなければ、何も行わない。

buffer-invisibility-specを使用するための規約として、メジャーモードはbuffer-invisibility-specの要素、およびinvisibleプロパティの値として、自身のモード名を使用することになっている。

;; 省略記号を表示したければ:
(add-to-invisibility-spec '(my-symbol . t))
;; 表示したくなければ:
(add-to-invisibility-spec 'my-symbol)

(overlay-put (make-overlay beginning end)
             'invisible 'my-symbol)

;; 不可視状態が終わったら:
(remove-from-invisibility-spec '(my-symbol . t))
;; または各々を:
(remove-from-invisibility-spec 'my-symbol)

以下の関数を使用することにより、不可視性をチェックできます:

Function: invisible-p pos-or-prop

If pos-or-prop is a marker or number, this function returns a non-nil value if the text at that position is currently invisible.

pos-or-propが別の類のLispオブジェクトなら、テキストプロパティまたはオーバーレイプロパティとして可能な値を意味すると解釈される。この場合、buffer-invisibility-specのカレント値にもとづき、もしその値がテキストを不可視とするようなら、この関数は非nilをリターンする。

The return value of this function is t if the text would be completely hidden on display, or a non-nil, non-t value if the text would be replaced by an ellipsis.

通常、テキストを操作したりポイントを移動する関数は、そのテキストが不可視かどうかに注意を払わず、可視および不可視のテキストを同様に処理します。next-lineやprevious-lineのようなユーザーレベルの行移動関数は、line-move-ignore-invisibleが非nil(デフォルト)なら、不可視な改行を無視します。これらの関数は不可視な改行がそのバッファーに存在しないかのように振る舞いますが、これはそう振る舞うよう、明示的にプログラムされているからです。

あるコマンドが、不可視テキストの境界内側のポイントで終了した場合、メイン編集ループはその不可視テキストの両端のうちのいずれかにポイントを再配置します。そのコマンドの移動関数の全体的な方向と同じになるように、Emacsが再配置の方向は決定します。これに疑問がある場合には、挿入された文字がinvisibleプロパティを継承しないような位置を優先してください。加えて、そのテキストが省略記号で置換されず、コマンドが不可視テキスト内への移動のみを行う場合、ポイントを1文字余計に移動して、目に見えるようカーソルを移動することにより、そのコマンドの移動を反映するよう試みます。

したがって,コマンドが(通常のstickinessをもつ)不可視範囲に、後方へとポイントを移動した場合、Emacsはポイントをその範囲の先頭へと、後方に移動します。コマンドが不可視範囲へ前方にポイントを移動した場合には、Emacsは不可視テキストの前にある最初の可視文字へと、前方にポイントを移動して、その後さらに前方へ1文字余計に移動します。

これら不可視テキスト中間で終了するポイントにたいするこれらの調整(adjustments)は、disable-point-adjustmentを非nilにセットすることにより無効にできます。コマンド後のポイントの調整を参照してください。

インクリメンタル検索はマッチが不可視テキストを含む場合は、一時的および/または永続的に不可視オーバーレイを可視にすることができます。これを有効にするためには、そのオーバーレイが非nilのisearch-open-invisibleプロパティをもつ必要があります。プロパティの値は、そのオーバーレイを引数として呼び出される関数であるべきです。その関数は、オーバーレイを永続的に可視にする必要があります。これは検索からのexit時にマッチがそのオーバーレイに重なるときに使用されます。

検索の間、そのようなオーバーレイのinvisible、およびintangibleプロパティを一時的に変更することにより、オーバーレイは一時的に可視にされます。特定のオーバーレイにたいして、異なる方法でこれを行いたいなら、それをisearch-open-invisible-temporaryプロパティ(関数)に与えてください。その関数は2つの引数により呼び出されます。1つ目はそのオーバーレイ、2つ目はnilならオーバーレイを可視に、tなら再び不可視にします。

39.7 選択的な表示

選択的表示(selective display)とは、スクリーン上で特定の行を隠蔽する、関連する機能ペアーを指します。

1つ目の変種は明示的な選択的表示で、これはLispプログラム内で使用するようにデザインされています。これはテキスト変更により、どの行を隠すかを制御します。この種の隠蔽は現在では時代遅れです。かわりにinvisibleプロパティで同じ効果を得ることができます(不可視のテキストを参照)。

2つ目の変種は、インデントにもとづいて隠す行の選択を自動的に行います。この変種は、ユーザーレベルの機能としてデザインされています。

選択的表示を明示的に制御する方法では、改行(control-j)を復帰(control-m)に置換します。以前は行末に改行があった行は、これにより隠蔽されます。厳密に言うと、改行だけが行を分離できるので、これはもはや一時的には行ではなく、前の行の一部です。

選択的表示は編集コマンドに直接影響を与えません。たとえばC-f(forward-char)は、隠蔽された行へ気軽にポイントを移動します。しかし復帰文字による改行文字の置換は、いくつかの編集コマンドに影響を与えます。たとえばnext-lineは改行だけを検索するため、隠蔽された行をスキップします。選択的表示を使用するモードは、改行を考慮するコマンドを定義したり、テキストのどの部分を隠すか制御することもできます。

選択的表示されたバッファーをファイルに書き込む際には、control-mはすべて改行として出力されます。これはファイル内のテキストを読み取る際には、すべて問題なく隠蔽されずに表示されることを意味します。選択的表示は、Emacs内でだけ見られる効果です。

Variable: selective-display

このバッファーローカル変数は、選択的表示を有効にする。これは行、または行の一部を隠すことができることを意味する。

selective-displayの値がtなら、文字control-mが隠蔽されたテキストの開始をマークする。control-mと、それに後続する行の残りは表示されない。これは明示的な選択的表示である。
selective-displayの値が正の整数なら、それより多くの列によるインデントで始まる行は表示されない。

バッファーの一部が隠蔽されている際は、垂直移動コマンドはあたかもその部分を存在しないかのように処理して、1回のnext-lineコマンドで任意の行数の隠蔽された行をスキップできる。しかし(forward-charのような)文字移動コマンドは隠蔽された部分をスキップせず、(注意すれば)隠蔽された部分にたいしてテキストの挿入と削除が可能である。

以下の例では、selective-displayの値の変更による、バッファーfooの外観表示を示す。このバッファーのコンテンツは変更されない。

(setq selective-display nil)
     ⇒ nil

---------- Buffer: foo ----------
1 on this column
 2on this column
  3n this column
  3n this column
 2on this column
1 on this column
---------- Buffer: foo ----------

(setq selective-display 2)
     ⇒ 2

---------- Buffer: foo ----------
1 on this column
 2on this column
 2on this column
1 on this column
---------- Buffer: foo ----------

User Option: selective-display-ellipses

このバッファーローカル変数が非nilなら、Emacsは隠蔽されたテキストを後にともなう行の終端に、‘…’を表示する。この例は、前の例からの継続である。

(setq selective-display-ellipses t)
     ⇒ t

---------- Buffer: foo ----------
1 on this column
 2on this column ...
 2on this column
1 on this column
---------- Buffer: foo ----------

省略記号(‘…’)にたいして他のテキストを代替えするために、ディスプレイテーブルを使用できる。ディスプレーテーブルを参照のこと。

39.8 一時的な表示

一時的表示(temporary display)は、出力をバッファーに配して、それを編集用ではなく閲覧用としてユーザーに示すために、Lispプログラムにより使用されます。多くのヘルプコマンドは、この機能を使用します。

Macro: with-output-to-temp-buffer buffer-name body…

この関数は、buffer-nameという名前のバッファー(必要なら最初に作成される)にプリントされた任意の出力が挿入されるようアレンジ、さらにバッファーをHelpモードにして、body内のフォームを実行する(類似する以下のフォームwith-temp-buffer-windowを参照されたい)。最後に、そのバッファーはいずれかのウィンドウに表示されるが、そのウィンドウは選択されない。

body内のフォームが出力バッファーのメジャーモードを変更しないため、実行の最後においても依然としてHelpモードにあるなら、with-output-to-temp-bufferは最後にそのバッファーを読み取り専用するとともに、クリック可能なクロスリファレンスとなるよう、関数名と変数名のスキャンも行う。特にドキュメント文字列内のハイパーリンク上アイテムに関する詳細は、Tips for Documentation Stringsを参照のこと。

文字列buffer-nameは一時的なバッファーを指定し、これはあらかじめ存在する必要はない。引数はバッファーではなく文字列でなければならない。そのバッファーは最初に消去され(確認なし)、with-output-to-temp-bufferのexit後は未変更(unmodified)とマークされる。

with-output-to-temp-bufferはstandard-outputを一時的バッファーにバインドして、body内のフォームを評価する。body内のLisp出力関数を使用した出力のデフォルト出力先は、そのバッファーになる(しかしスクリーン表示、エコーエリア内のメッセージは、一般的な世界の感覚では“出力”であるものの、影響は受けない)。出力関数を参照のこと。

この構成の振る舞いをカスタマイズするために利用できるフックがいくつかあり、それらは以下にリストしてある。

リターン値は、body内の最後のフォームの値である。

---------- Buffer: foo ----------
 This is the contents of foo.
---------- Buffer: foo ----------

(with-output-to-temp-buffer "foo"
    (print 20)
    (print standard-output))
⇒ #<buffer foo>

---------- Buffer: foo ----------

20

#<buffer foo>

---------- Buffer: foo ----------

User Option: temp-buffer-show-function

この変数が非nilなら、with-output-to-temp-bufferはヘルプバッファーを表示する処理を行うために、その関数を呼び出す。この関数は、表示すべきバッファーという、1つの引数を受け取る。

with-output-to-temp-bufferが通常行うように、save-selected-window内部や選択されたウィンドウ内で、バッファーか選択された状態で、temp-buffer-show-hookを実行するのは、この関数にとってよいアイデアである。

Variable: temp-buffer-setup-hook: このノーマルフックは、bodyを評価する前に、with-output-to-temp-bufferにより実行される。フック実行時は、一時的バッファーがカレントになる。このフックは通常、そのバッファーをHelpモードにするための関数にセットアップされる。

Variable: temp-buffer-show-hook: このノーマルフックは、一時的バッファー表示後に、with-output-to-temp-bufferにより実行される。フック実行時は一時的バッファーがカレントになり、それが表示されているウィンドウが選択される。

Macro: with-temp-buffer-window buffer-or-name action quit-function body…

このマクロはwith-output-to-temp-bufferと類似している。with-output-to-temp-buffer構成同様、これはプリントされる任意の出力がbuffer-or-nameという名前のバッファーに挿入されるようにアレンジしてbodyを実行し、そのバッファーをいぜれかのウィンドウに表示する。しかしwith-output-to-temp-bufferとは異なり、このマクロはそのバッファーを自動的にHelpモードに切り替えない。

引数buffer-or-nameは、一時的バッファーを指定する。これはバッファー(既存でなければならない)、または文字列を指定でき、文字列の場合は必要ならその名前のバッファーが作成される。そのバッファーはwith-temp-buffer-windowのexit時、未変更かる読み取り専用とマークされる。

This macro does not call temp-buffer-show-function. Rather, it passes the action argument to display-buffer (see section 表示するウィンドウの選択) in order to display the buffer.

引数quit-functionが指定されていなければ、body内の最後のフォームの値がリターンされる。指定されている場合、それはそのバッファーを表示するウィンドウと、bodyの結果という、2つの引数で呼び出される。その場合、最終的なリターン値は何であれquit-functionがリターンした値となる。

このマクロは、with-output-to-temp-bufferにより実行される類似フックのかわりに、ノーマルフックtemp-buffer-window-setup-hookとtemp-buffer-window-show-hook使用する。

The two constructs described next are mostly identical to with-temp-buffer-window but differ from it as specified:

Macro: with-current-buffer-window buffer-or-name action quit-function &rest body: This macro is like with-temp-buffer-window but unlike that makes the buffer specified by buffer-or-name current for running body.

Macro: with-displayed-buffer-window buffer-or-name action quit-function &rest body: This macro is like with-current-buffer-window but unlike that displays the buffer specified by buffer-or-name before running body.

A window showing a temporary buffer can be fitted to the size of that buffer using the following mode:

User Option: temp-buffer-resize-mode

When this minor mode is enabled, windows showing a temporary buffer are automatically resized to fit their buffer’s contents.

A window is resized if and only if it has been specially created for the buffer. In particular, windows that have shown another buffer before are not resized. By default, this mode uses fit-window-to-buffer (see section ウィンドウのリサイズ) for resizing. You can specify a different function by customizing the options temp-buffer-max-height and temp-buffer-max-width below.

User Option: temp-buffer-max-height: This option specifies the maximum height (in lines) of a window displaying a temporary buffer when temp-buffer-resize-mode is enabled. It can also be a function to be called to choose the height for such a buffer. It gets one argument, the buffer, and should return a positive integer. At the time the function is called, the window to be resized is selected.

User Option: temp-buffer-max-width: This option specifies the maximum width of a window (in columns) displaying a temporary buffer when temp-buffer-resize-mode is enabled. It can also be a function to be called to choose the width for such a buffer. It gets one argument, the buffer, and should return a positive integer. At the time the function is called, the window to be resized is selected.

The following function uses the current buffer for temporary display:

Function: momentary-string-display string position &optional char message

この関数は、カレントバッファー内のpositionに、stringを瞬間表示(momentarily display)する。これはundoリストや、そのバッファーの変更状態(modification status)に影響を与えない。

瞬間表示は、次の入力イベントまで留まる。次の入力イベントがcharなら、momentary-string-displayはそれを無視してリターンする。それ以外なら、そのイベントは後続の入力として使用するためにバッファーされる。つまりcharとタイプすると、表示からその文字列を単に削除して、charではない(たとえば)C-fとタイプすると表示からその文字列を削除して、後で(おそらく)ポイントを前方へ移動するだろう。引数charのデフォルトはスペース。

momentary-string-displayのリターン値に意味はない。

文字列stringがコントロール文字を含まなければ、before-stringプロパティでオーバーレイを作成(してその後削除)することで、より一般的に同じことを行うことができる。オーバーレイのプロパティを参照のこと。

messagegが非nilなら、バッファー内にstringが表示されている間は、エコーエリアにそれが表示される。nilならデフォルトは、継続するためにはcharをタイプするよう告げるメッセージである。

以下の例ではポイントは最初、2行目の先頭に置かれている:

---------- Buffer: foo ----------
This is the contents of foo.
∗Second line.
---------- Buffer: foo ----------

(momentary-string-display
  "**** Important Message! ****"
  (point) ?\r
  "Type RET when done reading")
⇒ t

---------- Buffer: foo ----------
This is the contents of foo.
**** Important Message! ****Second line.
---------- Buffer: foo ----------

---------- Echo Area ----------
Type RET when done reading
---------- Echo Area ----------

39.9 オーバーレイ

プレゼンテーション機能として、バッファーのテキストのスクリーン上の見栄えを変更するために、オーバーレイ(overlay)を使用できます。オーバーレイとは、個々のバッファーに属するオブジェクトであり、指定された開始と終了をもっています。確認したりセットすることができるプロパティももっています。それらはオーバーレイをもつテキストの表示に影響を与えます。

オーバーレイの視覚的効果は、対応するテキストプロパティと同様です(テキストのプロパティを参照)。しかし実装が異なるため、オーバーレイは一般的にスケーラブルではありません(処理数に応じて、バッファー内のオーバーレイ数に比例した時間を要する)。バッファー内の多数の部分の視覚的外観に効果を及ぼす必要がある場合は、テキストプロパティの使用を推奨します。

オーバーレイは、その開始と終了を記録するために、マーカーを使用します。したがってバッファーのテキスト編集では、すべてのオーバーレイがそのテキストに留まるように、開始と終了が調整されます。オーバーレイ作成時には、オーバーレイ先頭、同様に終端にテキストが挿入された場合に、それがオーバーレイの内側あるいは外側であるべきかを指定できます。

39.9.1 オーバーレイの管理

このセクションでは、オーバーレイの作成、削除、移動、およびそれらのコンテンツを調べる関数を説明します。オーバーレイはバッファーのコンテンツの一部ではないので、その変更はバッファーのundoリストに記録されません。

Function: overlayp object: この関数は、objectがオーバーレイならtをリターンする。

Function: make-overlay start end &optional buffer front-advance rear-advance

この関数はbufferに属し、startからendの範囲のオーバーレイを作成してリターンする。startとendはいずれもバッファーの位置を指定しなければならず、整数またはマーカーを指定できる。bufferが省略された場合、そのオーバーレイはカレントバッファーに作成される。

An overlay whose start and end specify the same buffer position is known as empty. A non-empty overlay can become empty if the text between its start and end is deleted. When that happens, the overlay is by default not deleted, but you can cause it to be deleted by giving it the ‘evaporate’ property (see section evaporate property).

引数front-advanceとrear-advanceはそれぞれ、オーバーレイの開始と終了にたいするマーカーの挿入タイプを指定する。Marker 挿入タイプを参照のこと。どちらもnil(デフォルト)なら、そのオーバーレイは先頭に挿入された任意のテキストを含むように拡張されるが、終端に挿入されたテキストにたいしては拡張されない。front-advanceが非nilなら、オーバーレイの先頭に挿入されたテキストは、オーバーレイから除外される。rear-advanceが非nilなら、オーバーレイの終端に挿入されたテキストは、オーバーレイに含まれる。

Function: overlay-start overlay: この関数は、overlayが開始する位置を整数でリターンする。

Function: overlay-end overlay: この関数は、overlayが終了する位置を整数でリターンする。

Function: overlay-buffer overlay: この関数は、overlayが所属するバッファーをリターンする。overlayが削除されていればnilをリターンする。

Function: delete-overlay overlay

この関数はoverlayを削除する。そのオーバーレイはLispオブジェクトとして存在し続け、そのプロパティリストは変更されないが、バッファーへの所属と表示にたいするすべての効果は失う。

削除済みオーバーレイが、永続的に非接続という訳ではない。move-overlayを呼び出すことにより、バッファー内の位置を与えることができる。

Function: move-overlay overlay start end &optional buffer

この関数はoverlayをbufferに移動して、その境界をstartとendに配する。startとendの引数はいずれもバッファーの位置を指定しなければならず、整数またはマーカーを指定できる。

bufferが省略された場合、overlayはすでに関連付けられている同じバッファーに留まる。さらにoverlayが削除されていたら、それをカレントバッファーに所属させる。

リターン値はoverlay。

This is the only valid way to change the endpoints of an overlay. Do not try modifying the markers in the overlay by hand, as that fails to update other vital data structures and can cause some overlays to be lost.

Function: remove-overlays &optional start end name value

この関数は、プロパティnameが値valueをもつ、startとendの間のすべてのオーバーレイを削除する。これによりオーバーレイの両端位置が変更されたり、分割される可能がある。

nameが省略またはnilなら、それは指定されたリージョン内のすべてのオーバーレイを削除することを意味する。startおよび/またはendが省略またはnilなら、それぞれバッファーの先頭と終端を意味する。したがって(remove-overlays)は、カレントバッファー内のすべてのオーバーレイを削除する。

Function: copy-overlay overlay: この関数はoverlayのコピーをリターンする。このコピーはoverlayと同じ両端位置とプロパティをもつ。しかしオーバーレイの開始と終了にたいするマーカー挿入タイプは、デフォルト値にセットされる(Marker 挿入タイプを参照)。

以下にいくつか例を示します:

;; オーバーレイの作成
(setq foo (make-overlay 1 10))
     ⇒ #<overlay from 1 to 10 in display.texi>
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 10
(overlay-buffer foo)
     ⇒ #<buffer display.texi>
;; 後でチェックできるようプロパティ付与
(overlay-put foo 'happy t)
     ⇒ t
;; プロパティが付与されたか検証
(overlay-get foo 'happy)
     ⇒ t
;; オーバーレイを移動
(move-overlay foo 5 20)
     ⇒ #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
     ⇒ 5
(overlay-end foo)
     ⇒ 20
;; オーバーレイを削除
(delete-overlay foo)
     ⇒ nil
;; 削除されたか検証
foo
     ⇒ #<overlay in no buffer>
;; 削除済みオーバーレイは位置をもたない
(overlay-start foo)
     ⇒ nil
(overlay-end foo)
     ⇒ nil
(overlay-buffer foo)
     ⇒ nil
;; オーバーレイの削除取り消し
(move-overlay foo 1 20)
     ⇒ #<overlay from 1 to 20 in display.texi>
;; 結果の検証
(overlay-start foo)
     ⇒ 1
(overlay-end foo)
     ⇒ 20
(overlay-buffer foo)
     ⇒ #<buffer display.texi>
;; オーバーレイの移動と削除では、オーバーレイのプロパティは変更されない
(overlay-get foo 'happy)
     ⇒ t

Emacs stores the overlays of each buffer in two lists, divided around an arbitrary center position. One list extends backwards through the buffer from that center position, and the other extends forwards from that center position. The center position can be anywhere in the buffer.

Function: overlay-recenter pos: この関数は、カレントバッファーのオーバーレイを、位置posの周辺に再センタリングする。これにより位置pos近傍のオーバーレイの照合は高速になるが、posから離れた位置にたいしては低速になる。

バッファーを前方にスキャンしてオーバーレイを作成するループは、最初に(overlay-recenter (point-max))を行うことにより高速になる可能性があります。

39.9.2 オーバーレイのプロパティ

オーバーレイプロパティは、文字が表示される方法をどちらのソースからも取得できるという点において、テキストプロパティと似ています。しかしほとんどの観点で、両者は異なります。これらの比較はテキストのプロパティを参照してください。

テキストプロパティは、そのテキストの一部として考えることができます。オーバーレイとそのプロパティは、特にテキストの一部としてはみなされません。したがって、さまざまなバッファーや文字列の間でテキストをコピーすると、テキストプロパティは保持されますが、オーバーレイを保持しようとは試みません。バッファーのテキストプロパティの変更は、そのバッファーを変更済みとマークしますが、オーバーレイの移動やプロパティの変更は違います。テキストプロパティの変更とは異なり、オーバーレイプロパティの変更は、バッファーのundoリストに記録されません。

Since more than one overlay can specify a property value for the same character, Emacs lets you specify a priority value of each overlay. The priority value is used to decide which of the overlapping overlays will “win”.

以下の関数は、オーバーレイのプロパティの読み取りとセットを行います:

Function: overlay-get overlay prop: この関数は、overlay内に記録されたプロパティpropの値をリターンする。そのプロパティにたいしてoverlayが何も値を記録していないが、シンボルであるようなcategoryプロパティをもつ場合は、そのシンボルのpropプロパティが使用される。それ以外なら値はnil。

Function: overlay-put overlay prop value: この関数は、overlay内に記録されたプロパティpropの値に、valueをセットする。リターン値はvalue。

Function: overlay-properties overlay: これは、overlayのプロパティリストのコピーをリターンする。

与えられた文字にたいしてテキストプロパティとオーバーレイプロパティの両方をチェックする関数get-char-propertyも参照してください。テキストプロパティを調べるを参照してください。

多くのオーバーレイプロパティには特別な意味があります。以下はそれらのテーブルです:

priority

このプロパティの値は、そのオーバーレイの優先度を決定する。優先度にたいして値を指定したければ、nil(か0)、または正の整数を使用すること。それ以外のすべての値にたいして、動作は未定義である。

The priority matters when two or more overlays cover the same character and both specify the same property; the one whose priority value is larger overrides the other. (For the face property, the higher priority overlay’s value does not completely override the other value; instead, its face attributes override the face attributes of the lower priority face property.) If two overlays have the same priority value, and one is nested in the other, then the inner one will prevail over the outer one. If neither is nested in the other then you should not make assumptions about which overlay will prevail.

現在のところ、すべてのオーバーレイはテキストプロパティより優先される。

Note that Emacs sometimes uses non-numeric priority values for some of its internal overlays, so do not try to do arithmetic on the priority of an overlay (unless it is one that you created). In particular, the overlay used for showing the region uses a priority value of the form (primary . secondary), where the primary value is used as described above, and secondary is the fallback value used when primary and the nesting considerations fail to resolve the precedence between overlays. However, you are advised not to design Lisp programs based on this implementation detail; if you need to put overlays in priority order, use the sorted argument of overlays-at. See section オーバーレイにたいする検索.

window

windowプロパティが非nilなら、そのオーバーレイはそのウィンドウだけに適用される。

category

オーバーレイがcategoryプロパティをもつなら、それをそのオーバーレイのカテゴリー(category)と呼ぶ。これはシンボルであること。そのシンボルのプロパティは、そのオーバーレイのプロパティにたいしてデフォルトの役割を果たす。

face

このプロパティはテキストの外観を制御する(フェイスを参照)。プロパティの値は以下のいずれか:

フェイス名(シンボルか文字列)。
anonymousフェイス: (keyword value …)という形式のプロパティリストで、keywordはフェイス属性名、valueはその属性の値。
フェイスのリスト。リストの要素はそれぞれフェイス名か、anonymousフェイスのいずれかであること。これはリストされた各フェイスの属性を集約するフェイスを指定する。このリスト内で先に出現するフェイスが、より高い優先度をもつ。
(foreground-color . color-name)または(background-color . color-name)という形式のコンスセル。これは(:foreground color-name)や(:background color-name)と同様、フォアグラウンドとバックグラウンドのカラーを指定する。この形式は後方互換性のためだけにサポートされており、避けるべきである。

mouse-face

このプロパティは、マウスがオーバーレイ範囲内にあるとき、faceのかわりに使用される。しかしEmacsは、このプロパティのテキストのサイズを変更する、すべてのフェイス属性(:height、:weight、:slant)を無視する。これらの属性は、ハイライトされていないテキストでは、常に同一である。

display

このプロパティは、テキストが表示される方法を変更する、さまざまな機能をアクティブにする。たとえばこれは、テキストの外観を縦長(taller)や横長(shorter)にしたり、高く(higher)したり低く(lower)したり、イメージで置き換える。displayプロパティを参照のこと。

help-echo

あるオーバーレイがhelp-echoプロパティをもつなら、そのオーバーレイ内のテキスト上にマウスを移動した際、Emacsはエコーエリアまたはツールチップウィンドウにヘルプ文字列を表示する。詳細はText help-echoを参照のこと。

field

同じfieldプロパティをもつ連続する文字は、フィールド(field)を形成する。forward-wordやbeginning-of-lineを含むいくつかの移動関数は、フィールド境界で移動を停止する。フィールドの定義と使用を参照のこと。

modification-hooks

このプロパティの値は、オーバーレイ内の任意の文字の変更、またはオーバーレイの厳密に内側にテキストが挿入された場合に呼び出される、関数のリストである。

このフックの関数は、各変更の前後両方で呼び出される。これらの関数が受け取った情報を保存し、呼び出し間で記録を比較すれば、バッファー内のテキストでどのような変更が行われたかを、正確に判断できる。

変更前に呼び出された際、各関数はオーバーレイ、nil、変更されたテキスト範囲の開始と終了という、4つの引数を受け取る。

変更後に呼び出された際、各関数はオーバーレイ、t、変更されたテキスト範囲の開始と終了、およびその範囲により置き換えられた変更前のテキスト長という、5つの引数を受け取る(変更前の長さは、挿入では0、削除では削除された文字数であり、変更後の先頭と終端が等しくなる)。

これらの関数がバッファーを変更する場合は、これらのフックを呼び出す内部的メカニズムの混乱を避けるために、それを行う前後でinhibit-modification-hooksをtにバインドすること。

テキストプロパティもmodification-hooksプロパティをサポートするが、詳細は幾分か異なる(特殊な意味をもつプロパティを参照)。

insert-in-front-hooks

このプロパティの値は、オーバーレイ先頭へのテキスト挿入前後に呼び出される、関数のリストである。呼び出し方は、modification-hooksの関数と同様。

insert-behind-hooks

このプロパティの値は、オーバーレイ終端へのテキスト挿入前後に呼び出される、関数のリストである。呼び出し方は、modification-hooksの関数と同様。

invisible

invisibleプロパティにより、オーバーレイ内のテキストを不可視似出来る。これはそのテキストが、スクリーン上に表示されないことを意味する。詳細は、See section 不可視のテキストを下さいのこと。

intangible

The intangible property on an overlay works just like the intangible text property. It is obsolete. See section 特殊な意味をもつプロパティ, for details.

isearch-open-invisible

このプロパティは、インクリメンタル検索にたいして、最後のマッチがそのオーバーレイに重なる場合に、不可視なオーバーレイを永続的に可視にする方法を告げる。不可視のテキストを参照のこと。

isearch-open-invisible-temporary

このプロパティは、インクリメンタル検索にたいして、検索の間に、不可視なオーバーレイを一時的に可視にする方法を告げる。不可視のテキストを参照のこと。

before-string

このプロパティの値は、オーバーレイ先頭に表示するために追加する文字列である。この文字列は、いかなる意味においてもバッファー内には表れず、スクリーン上にのみ表れる。

after-string

このプロパティの値は、オーバーレイ終端に表示するために追加する文字列である。この文字列は、いかなる意味においてもバッファー内には表れず、スクリーン上にのみ表れる。

line-prefix

このプロパティは、表示時にそれぞれの非継続行の後に追加する、表示仕様(display spec)を指定する。切り詰めを参照のこと。

wrap-prefix

このプロパティは、表示時にそれぞれの継続行の前に追加する、表示仕様(display spec)を指定する。切り詰めを参照のこと。

evaporate

If this property is non-nil, the overlay is deleted automatically if it becomes empty (i.e., if its length becomes zero). If you give an empty overlay (see section empty overlay) a non-nil evaporate property, that deletes it immediately. Note that, unless an overlay has this property, it will not be deleted when the text between its starting and ending positions is deleted from the buffer.

keymap

このプロパティがからnilなら、それはそのテキスト範囲にたいしてキーマップを指定する。このキーマップは、ポイントの後の文字がそのオーバーレイ内にあるときに使用され、他のほとんどのキーマップより優先される。アクティブなキーマップを参照のこと。

local-map

local-mapプロパティはkeymapプロパティと同様だが、既存のキーマップに付け加えるのではなく、バッファーのローカルマップを置き換える点が異なる。これは、そのキーマップがマイナーモードキーマップより低い優先度をもつことも意味する。

keymapとlocal-mapプロパティは、before-string、after-string、displayプロパティにより表示された文字列には影響しません。これはポイントがその文字列上にない場合の、マウスクリックや、その文字列に関する他のマウスイベントにのみ関係があります。その文字列に特別なマウスイベントをバインドするには、そのイベントをkeymapかlocal-mapプロパティに割り当てます。特殊な意味をもつプロパティを参照してください。

39.9.3 オーバーレイにたいする検索

Function: overlays-at pos &optional sorted

この関数は、カレントバッファー内の位置posにある文字をカバーする、すべてオーバーレイのリストをリターンする。sortedが非nilならリストは優先度降順、それ以外なら特定の順にはソートされない。オーバーレイがpos、またはそれより前から始まり、かつposの後で終わる場合、位置posはオーバーレイに含まれる。

使い方を説明するために、ポイント位置の文字にたいして、プロパティpropを指定するオーバーレイのリストをリターンするLisp関数である:

(defun find-overlays-specifying (prop)
  (let ((overlays (overlays-at (point)))
        found)
    (while overlays
      (let ((overlay (car overlays)))
        (if (overlay-get overlay prop)
            (setq found (cons overlay found))))
      (setq overlays (cdr overlays)))
    found))

Function: overlays-in beg end: This function returns a list of the overlays that overlap the region beg through end. An overlay overlaps with a region if it contains one or more characters in the region; empty overlays (see section empty overlay) overlap if they are at beg, strictly between beg and end, or at end when end denotes the position at the end of the buffer.

Function: next-overlay-change pos: この関数はposの後にあるオーバーレイの、開始または終了となるバッファー位置をリターンする。それが存在しなければ(point-max)をリターンする。

Function: previous-overlay-change pos: この関数はposの前にあるオーバーレイの、開始または終了となるバッファー位置をリターンする。それが存在しなければ(point-min)をリターンする。

以下に例として、プリミティブ関数next-single-char-property-change(テキストプロパティの検索関数を参照)の、単純化(かつ非効率的な)したバージョンを示します。これは位置posから前方へ、与えられたプロパティpropにたいして、オーバーレイプロパティまたはテキストプロパティのいずれかの値が変化した、次の位置を検索します。

(defun next-single-char-property-change (position prop)
  (save-excursion
    (goto-char position)
    (let ((propval (get-char-property (point) prop)))
      (while (and (not (eobp))
                  (eq (get-char-property (point) prop) propval))
        (goto-char (min (next-overlay-change (point))
                        (next-single-property-change (point) prop)))))
    (point)))

39.10 表示されるテキストのサイズ

すべての文字が同じ幅をもつ訳ではないので、以下の関数により文字の幅をチェックできます。関連する関数については、インデント用のプリミティブとスクリーン行単位の移動を参照してください。

Function: char-width char: この関数は、文字charがカレントバッファーに表示された場合(つまりそのバッファーのディスプレイテーブルがあれば、それを考慮に入れる。ディスプレーテーブルを参照されたい)の幅を、列数でリターンする。タブ文字の幅は、通常はtab-widthである(通常の表示の慣習を参照)。

Function: string-width string: この関数は、文字列stringがカレントバッファー、および選択されたウィンドウに表示された場合の幅を、列数でリターンする。

Function: truncate-string-to-width string width &optional start-column padding ellipsis

この関数はstringの一部を、列数widthにフィット新たな文字列としてリターンする。

stringがwidthに満たない場合、その文字列終端が結果の終端となる。string内の1つの複数列文字が、列widthを超えて跨がる場合、その文字は結果に含まれない。つまり結果はwidthより短くなるかもしれないが、それを超えることはできない。

オプション引数start-columnは、開始列を指定する。これが非nilなら、その文字列の最初のstart-column列は、値から省かれる。string内の1つの複数列文字が、列start-columnを超えて跨がる場合、その文字は結果に含まれない。

オプション引数paddingが非nilなら、結果となる文字列の幅を正確にwidth列に拡張するために、パディング文字が追加される。結果文字列がwidthより短ければ、結果文字列の終端にパディング文字が使用される。string内の1つの複数列文字が列start-columnを跨ぐ場合は、先頭にもパディング文字が使用される。

If ellipsis is non-nil, it should be a string which will replace the end of string (including any padding) if it extends beyond width, unless the display width of string is equal to or less than the display width of ellipsis. If ellipsis is non-nil and not a string, it stands for the value of the variable truncate-string-ellipsis.

(truncate-string-to-width "\tab\t" 12 4)
     ⇒ "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\s)
     ⇒ "    ab  "

The following function returns the size in pixels of text as if it were displayed in a given window. This function is used by fit-window-to-buffer and fit-frame-to-buffer (see section ウィンドウのリサイズ) to make a window exactly as large as the text it contains.

Function: window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line

この関数は、windowのバッファーのテキストサイズを、ピクセル単位でリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウ。リターン値は、任意のテキスト行の最大ピクセル幅と、すべてのテキスト行の最大ピクセル高さのコンスである。

オプション引数fromが非nilなら、それは考慮すべき最初のテキスト位置を指定し、デフォルトはそのバッファーのアクセス可能な最小の位置である。fromがtなら、それは改行文字ではない、アクセス可能な最小位置を使用する。オプション引数toが非nilなら、それは考慮すべき最後のテキスト位置を指定し、デフォルトはそのバッファーのアクセス可能な最大の位置である。toがtなら、それは改行文字ではない、アクセス可能な最大位置を使用する。

オプション引数x-limitが非nilなら、それはリターンされ得る、最大ピクセル幅を指定する。x-limitがnilまたは省略された場合には、windowのbody(ウィンドウのサイズを参照)のピクセル幅を使用する。これは、呼び出し側がwindowの幅の変更を意図しない場合に有用である。それ以外なら、呼び出し側はここで想定されるwindowのbodyの、最大幅を指定するべきである。X座標を超えるテキストのx-limitは無視される。長い行の幅の計算には多くの時間を要する可能性があるので、特にいずれにせよ切り詰められるであろう長い行を含むバッファーの場合には、必要に応じて、この引数の値を小さくすることは、よいアイデアである。

オプション引数y-limitが非nilなら、それはリターンされ得る、最大ピクセル高さを指定する。Y座標を超えるテキストのy-limitは無視される。大きなバッファーのピクセル高さの計算には多くの時間を要する可能性があるので、特に呼び出し側がバッファーのサイズを知らない場合、この変数の指定は合理的である。

オプション引数mode-and-header-lineがnilまたは省略された場合は、リターン値にwindowのモードラインとヘッダーラインの高さを含めないことを意味する。これがシンボルmode-lineまたはheader-lineのいずれかなら、それらが存在する場合は、リターン値にそのラインの高さだけを含める。これがtなら、存在する場合は両方の高さをリターン値に含める。

window-text-pixel-size treats the text displayed in a window as a whole and does not care about the size of individual lines. The following function does.

Function: window-lines-pixel-dimensions &optional window first last body inverse left

This function calculates the pixel dimensions of each line displayed in the specified window. It does so by walking window’s current glyph matrix—a matrix storing the glyph (see section グリフ) of each buffer character currently displayed in window. If successful, it returns a list of cons pairs representing the x- and y-coordinates of the lower right corner of the last character of each line. Coordinates are measured in pixels from an origin (0, 0) at the top-left corner of window. window must be a live window and defaults to the selected one.

If the optional argument first is an integer, it denotes the index (starting with 0) of the first line of window’s glyph matrix to be returned. Note that if window has a header line, the line with index 0 is that header line. If first is nil, the first line to be considered is determined by the value of the optional argument body: If body is non-nil, this means to start with the first line of window’s body, skipping any header line, if present. Otherwise, this function will start with the first line of window’s glyph matrix, possibly the header line.

If the optional argument last is an integer, it denotes the index of the last line of window’s glyph matrix that shall be returned. If last is nil, the last line to be considered is determined by the value of body: If body is non-nil, this means to use the last line of window’s body, omitting window’s mode line, if present. Otherwise, this means to use the last line of window which may be the mode line.

The optional argument inverse, if nil, means that the y-pixel value returned for any line specifies the distance in pixels from the left edge (body edge if body is non-nil) of window to the right edge of the last glyph of that line. inverse non-nil means that the y-pixel value returned for any line specifies the distance in pixels from the right edge of the last glyph of that line to the right edge (body edge if body is non-nil) of window. This is useful for determining the amount of slack space at the end of each line.

The optional argument left, if non-nil means to return the x- and y-coordinates of the lower left corner of the leftmost character on each line. This is the value that should be used for windows that mostly display text from right to left.

If left is non-nil and inverse is nil, this means that the y-pixel value returned for any line specifies the distance in pixels from the left edge of the last (leftmost) glyph of that line to the right edge (body edge if body is non-nil) of window. If left and inverse are both non-nil, the y-pixel value returned for any line specifies the distance in pixels from the left edge (body edge if body is non-nil) of window to the left edge of the last (leftmost) glyph of that line.

This function returns nil if the current glyph matrix of window is not up-to-date which usually happens when Emacs is busy, for example, when processing a command. The value should be retrievable though when this function is run from an idle timer with a delay of zero seconds.

Function: line-pixel-height: This function returns the height in pixels of the line at point in the selected window. The value includes the line spacing of the line (see section 行の高さ).

When a buffer is displayed with line numbers (see Display Custom in The GNU Emacs Manual), it is sometimes useful to know the width taken for displaying the line numbers. The following function is for Lisp programs which need this information for layout calculations.

Function: line-number-display-width &optional pixelwise: This function returns the width used for displaying the line numbers in the selected window. If the optional argument pixelwise is the symbol columns, the return value is a float number of the frame’s canonical columns; if pixelwise is t or any other non-nil value, the value is an integer and is measured in pixels. If pixelwise is omitted or nil, the value is the integer number of columns of the font defined for the line-number face, and doesn’t include the 2 columns used to pad the numbers on display. If line numbers are not displayed in the selected window, the value is zero regardless of the value of pixelwise. Use with-selected-window (see section ウィンドウの選択) if you need this information about another window.

39.11 行の高さ

各ディスプレイ行のトータル高さは、その行のコンテンツ高さに、そのディスプレイ上部または下部にオプションで追加される垂直行スペーシングを加えて構成されます。

The height of the line contents is the maximum height of any character or image on that display line, including the final newline if there is one. (A display line that is continued doesn’t include a final newline.) That is the default line height, if you do nothing to specify a greater height. (In the most common case, this equals the height of the corresponding frame’s default font, see Frame Font.)

より大きい行高さを明示的に指定するためにはディスプレイ行の絶対高さ、または垂直スペースを指定することによる、複数の方法が存在します。しかし何を指定したかに関わらず、実際の行高さがデフォルトの高さより小さくなることはありません。

改行は、その改行で終わるディスプレイ行のトータル高さを制御する、テキストプロパティまたはオーバーレイプロパティline-heightをもつことができます。

If the property value is t, the newline character has no effect on the displayed height of the line—the visible contents alone determine the height. The line-spacing property, described below, is also ignored in this case. This is useful for tiling small images (or image slices) without adding blank areas between the images.

If the property value is a list of the form (height total), that adds extra space below the display line. First Emacs uses height as a height spec to control extra space above the line; then it adds enough space below the line to bring the total line height up to total. In this case, any value of line-spacing property for the newline is ignored.

他の種類のプロパティ値は高さspec(height spec)です。これは行の高さを指定する数値に変換されます。高さspecを記述するためには複数の方法があります。以下はそれらが数値に変換される方法です:

integer: 高さspecが正の整数なら、高さの値はその整数。
float: 高さspecが浮動小数点数floatなら、高さ数値はそのフレームのデフォルト行高さのfloat倍。
(face . ratio): 高さspecがこのフォーマットのコンスなら、高さ数値はフェイスfaceの高さのratio倍。ratioには任意の型の数値を指定でき、nilは1のratioを意味する。faceがtなら、カレントフェイスを参照する。
(nil . ratio): 高さspecがこのフォーマットのコンスなら、高さ数値はその行のコンテンツ高さのratio倍。

したがって、任意の有効な種々の高さspecにより、ピクセル単位で高さが決定されます。行のコンテンツ高さがこれより小さければ、Emacsは指定されたトータル高さになるよう、余分な垂直スペースを行の上部に追加します。

line-heightプロパティを指定しない場合、その行の高さは行のコンテンツ高さとに行スペーシングを追加して構成されます。Emacsの異なるさまざまな部分のテキストにたいして、行スペーシングを指定する複数の方法が存在します。

グラフィカルなディスプレイでは、フレームパラメーターline-spacing(レイアウトのパラメーターを参照)を使用することにより、フレーム内のすべての行にたいして行スペーシングを指定できます。しかしline-spacingのデフォルト値が非nilなら、それはそのフレームのフレームパラメーターline-spacingをオーバーライドします。整数は行の下部に配するピクセル数を指定します。浮動小数点数はフレームのデフォルト行高さに相対的にスペーシングを指定します。

バッファーローカル変数line-spacingを通じて、バッファー内のすべての行の行スペーシングを指定できます。整数は行の下部に配するピクセル数を指定します。浮動小数点数はデフォルトフレーム行高さに相対的にスペーシングを指定します。これは、そのフレームにたいして指定された行スペーシングをオーバーライドします。

Finally, a newline can have a line-spacing text or overlay property that can enlarge the default frame line spacing and the buffer local line-spacing variable: if its value is larger than the buffer or frame defaults, that larger value is used instead, for the display line ending in that newline.

種々の方法により、これらのメカニズムは各行のスペーシングにたいするLisp値を指定します。値は高さspecで、これは上述したLisp値に変換されます。しかしこの場合高さ数値は行高さではなく行スペーシングを指定します。

テキスト端末では、行スペーシングは変更できません。

39.12 フェイス

フェイス(face)とはフォント、フォアグラウンドカラー、バックグラウンドカラー、オプションのアンダーライン等のテキストを表示するための、グラフィカルな属性のコレクションのことです。フェイスはEmacsがバッファー内、同様にモードラインのようなフレームの他の部分で、テキストを表示する方法を制御します。

フェイスを表現する1つの方法として、(:foreground "red" :weight bold)のような属性のプロパティリストがあります。このようなリストは、anonymousフェイス(anonymous face)と呼ばれます。たとえばfaceテキストプロパティとしてanonymousフェイスを割り当てることができ、Emacsは指定された属性でテキストを表示するでしょう。特殊な意味をもつプロパティを参照してください。

より一般的には、フェイスはフェイス名(face name)を通じて参照されます。これはフェイス属性のセットに関連付けられたLispシンボル¹⁹。です。名前つきフェイスはdeffaceマクロを使用して定義できます(フェイスの定義を参照)。Emacsにはいくつかの標準名前つきフェイスが同梱されています(基本的なフェイスを参照)。

Many parts of Emacs require named faces, and do not accept anonymous faces. These include the functions documented in フェイス属性のための関数, and the variable font-lock-keywords (see section 検索ベースのフォント化). Unless otherwise stated, we will use the term face to refer only to named faces.

Function: facep object: この関数はobjectが名前つきフェイス(フェイス名の役目をもつLispシンボルまたは文字列)なら、非nilをリターンする。それ以外ならnilをリターンする。

39.12.1 フェイスの属性		フェイスとは?
39.12.2 フェイスの定義		フェイスを定義する方法。
39.12.3 フェイス属性のための関数		フェイス属性の確認およびセットを行う関数。
39.12.4 フェイスの表示		ある文字にたいして指定されたフェイスをEmacsが組み合わせる方法。
39.12.5 フェイスのリマップ		フェイスを別の定義にリマップする。
39.12.6 フェイスを処理するための関数		フェイスの定義、および確認する方法。
39.12.7 フェイスの自動割り当て		自動的にフェイスを割り当てるフック。
39.12.8 基本的なフェイス		デフォルトで定義されるフェイス。
39.12.9 フォントの選択		あるフェイスに最適なフォントを見つける。
39.12.10 フォントの照会		利用可能なフォント名とそれらの情報の照会。
39.12.11 フォントセット		フォントセット、それは文字セットの範囲を処理するフォントコレクションである。
39.12.12 低レベルのフォント表現		文字表示フォントのLisp表現。

39.12.1 フェイスの属性

フェイス属性(Face attributes)は、フェイスの視覚的外観を決定します。以下はすべてのフェイス属性と、それらの可能な値と効果に関するテーブルです。

以下の値とは別に、各フェイス属性は値unspecifiedをもつことができます。この特殊な値は、フェイスがその属性を直接指定しないことを意味します。unspecified属性は、Emacsにかわりに親フェイス(以下の:inherit属性の記述を参照)を参照すること、それに失敗した場合は基礎フェイス(フェイスの表示を参照)を参照することを指示します。defaultフェイスはすべての属性を指定しなければなりません。

これらの属性のいくつかは、特定の種類のディスプレイにおいてのみ意味があります。ディスプレイが特定の属性を処理できなければ、その属性は無視されます。

:family

Font family name (a string). See Fonts in The GNU Emacs Manual, for more information about font families. The function font-family-list (see below) returns a list of available family names.

:foundry

:family属性により指定されるフォントファミリーにたいするフォントfoundry(font foundry)(文字列)。Fonts in The GNU Emacs Manualを参照のこと。

:width

相対的な文字幅。これはシンボルultra-condensed、extra-condensed、condensed、semi-condensed、normal、semi-expanded、expanded、extra-expanded、ultra-expandedのいずれかであること。

:height

フォントの高さ。もっともシンプルなケースでは1/10ポイントを単位とする整数。

値には基礎フェイス(underlying face)にたいして相対的に高さを指定する浮動小数点数、または関数も指定できる(フェイスの表示を参照)。浮動小数点数は基礎フェイスの高さをスケーリングする量を指定する。関数値は基礎フェイスの高さを単一の引数として呼び出され、新たなフェイスの高さをリターンする。関数が整数を引数として渡された場合には、整数をリターンしなければならない。

デフォルトフェイスの高さは、整数を使用して指定しなければならない。浮動小数点数および関数は受け入れられない。

:weight

フォントのweight。(太字から細字順に)シンボルultra-bold、extra-bold、bold、semi-bold、normal、semi-light、light、extra-light、ultra-lightのいずれか。可変輝度テキストをサポートするテキスト端末では、normalより大なweightはより高輝度、小なweightはより低輝度で表示される。

:slant

フォントのslant。シンボルitalic、oblique、normal、reverse-italic、reverse-obliqueのいずれか。可変輝度テキストをサポートするテキスト端末では、slantされたテキストはhalf-brightで表示される。

:foreground

フォアグラウンドカラー(文字列)。値にはシステム定義済みカラー、または16進カラー仕様を指定できる。カラー名を参照のこと。白黒ディスプレイでは、特定のグレー色調が点描パターンで実装されている。

:distant-foreground

Alternative foreground color, a string. This is like :foreground but the color is only used as a foreground when the background color is near to the foreground that would have been used. This is useful for example when marking text (i.e., the region face). If the text has a foreground that is visible with the region face, that foreground is used. If the foreground is near the region face background, :distant-foreground is used instead so the text is readable.

:background

バックグラウンドカラー(文字列)。値にはシステム定義済みカラー、または16進カラー仕様を指定できる。カラー名を参照のこと。

:underline

文字にアンダーラインを引くべきか否かと、その方法。:underline属性として可能な値は以下のとおり:

nil: アンダーラインを引かない。
t: そのフェイスのフォアグラウンドカラーでアンダーラインを引く。
color: 文字列colorで指定されたカラーでアンダーラインを引く。
(:color color :style style): colorは文字列、またはそのフェイスのフォアグラウンドカラーを意味するシンボルforeground-color。属性:colorの省略は、そのフェイスのフォアグラウンドカラーの使用を意味する。styleには直線を意味するline、または波線を意味するwaveいずれかのシンボルであること。属性:styleの省略は直線を意味する。

:overline

文字にオーバーラインを引くべきか否かと、そのカラー。値がtなら、そのフェイスのフォアグラウンドカラーを使用してオーバーラインを引く。値が文字列なら、そのカラーを使用してオーバーラインを引く。値nilはオーバーラインを引かないことを意味する。

:strike-through

文字に取り消し線を引くべきか否かと、そのカラー。値は:overlineで使用される値と同じ。

:box

文字周囲に枠(box)を描画するか否か、そのカラー、枠線の幅、3D外観。以下は:boxの可能な値と意味である:

nil

枠を描画しない。

t

幅1の枠線、フォアグラウンドカラーで枠を描画する。

color

幅1の枠線、カラーcolorで枠を描画する。

(:line-width width :color color :style style)

This way you can explicitly specify all aspects of the box. The value width specifies the width of the lines to draw; it defaults to 1. A negative width -n means to draw a line of width n whose top and bottom parts occupy the space of the underlying text, thus avoiding any increase in the character height.

値colorは描画するカラーを指定する。シンプルな枠線ではフェイスのフォアグラウンドカラー、3D枠線ではフェイスのバックグラウンドカラーがデフォルト。

値styleは3D枠線を描画するか否かを指定する。released-buttonなら、枠は押下された3Dボタンのような外観、pressed-buttonなら押下されていない3Dボタンのような外観、nilまたは省略された場合は2D枠線が使用される。

:inverse-video

文字が反転表示されて表示されるべきか否か。値はt(反転表示する)、またはnil(反転表示しない)であること。

:stipple

バックグラウンドの点描(ビットマップ)。

値には文字列を指定でき、それは外部形式Xビットマップデータを含むファイルの名前であること。ファイルは変数x-bitmap-file-pathにリストされるディレクトリー内で検索される。

かわりに(width height data)という形式のリストにより、ビットマップで直接値を指定できる。ここでwidthとheightはピクセル単位によるサイズ、dataは行単位でビットマップのrawビットを含む文字列。各行は文字列内で連続する(width + 7) / 8バイトを占める(最善の結果を得るためにはユニバイト文字列であるべき)。これは各行が常に少なくとも、1バイト全体を占めることを意味する。

値がnilなら、点描パターンを使用しないことを意味する。

これは特定のグレー色調を処理するために自動的に使用されるので、通常はstipple属性のセットは必要ない。

:font

The font used to display the face. Its value should be a font object or a fontset. See section 低レベルのフォント表現, for information about font objects, font specs, and font entities. See section フォントセット, for information about fontsets.

set-face-attribute(フェイス属性のための関数を参照)を使用してこの属性を指定する際にはフォントspec、フォントエンティティー、または文字列を与えることもできる。Emacsはそのような値を適切なフォントオブジェクトに変換して、実際の属性値としてそのフォントオブジェクトを格納する。文字列を指定する場合、その文字列のコンテンツはフォント名であること(Fonts in The GNU Emacs Manualを参照)。フォント名がワイルドカードを含むXLFDなら、Emacsはそれらのワイルドカードに最初にマッチするフォントを選択する。この属性の指定により、:family、:foundry、:width、:height、:weight、:slantの属性値も変更される。

:inherit

The name of a face from which to inherit attributes, or a list of face names. Attributes from inherited faces are merged into the face like an underlying face would be, with higher priority than underlying faces (see section フェイスの表示). If the face to inherit from is unspecified, it is treated the same as nil, since Emacs never merges :inherit attributes. If a list of faces is used, attributes from faces earlier in the list override those from later faces.

Function: font-family-list &optional frame: この関数は、利用可能なフォントファミリー名のリストをリターンする。オプション引数frameはそのテキストが表示されるフレームを指定する。これがnilなら選択されたフレームが使用される。

User Option: underline-minimum-offset: この変数は、アンダーラインが引かれたテキスト表示時に、ベースラインとアンダーライン間の最小距離を、ピクセル単位で指定する。

User Option: x-bitmap-file-path: この変数は:stipple属性のビットマップファイルを検索する、ディレクトリーのリストを指定する。

Function: bitmap-spec-p object: これはobjectが、:stipple(上記参照)での使用に適す有効なビットマップ仕様ならt、それ以外ならnilをリターンする。

39.12.2 フェイスの定義

フェイスを定義する通常の方法は、deffaceマクロを通じて定義する方法です。このマクロはフェイス名(シンボル)を、デフォルトのフェイスspec(face spec)と関連付けます。フェイスspecは、任意の与えられた端末上でフェイスがどの属性をもつべきかを指定する構成です。たとえばあるフェイスspecは、高カラー端末ではあるフォアグラウンドカラーを指定し、低カラー端末では異なるフォアグラウンドカラーを指定するかもしれません。

値がフェイス名であるような変数を作りたがる人がいます。ほとんどの場合、これは必要ありません。通常手順は、deffaceでフェイスを定義して、その名前を直接使用することです。

Macro: defface face spec doc [keyword value]…

このマクロは、specによりデフォルトフェイスspecが与えられるような、名前つきフェイスとしてfaceを宣言する。シンボルfaceはクォートせず、‘-face’で終わらないこと(冗長であろう)。引数docは、そのフェイスにたいするドキュメント文字列。追加のkeyword引数は、defgroupおよびdefcustomの場合と同じ意味をもつ(一般的なキーワードアイテムを参照)。

If face already has a default face spec, this macro does nothing.

デフォルトフェイスspecは、何もカスタマイゼーション(カスタマイズ設定を参照)の効果がないときに、faceの外観を決定する。faceが、(Customテーマやinitファイルから読み込んだカスタマイズにより)すでにカスタマイズ済みなら、その外観はデフォルトフェイスspecのspecをオーバーライドする、カスタムフェイスspecにより決定される。しかしその後カスタマイゼーションが削除されたなら、faceの外観は再びそのデフォルトフェイスspecにより決定されるだろう。

例外として、Emacs LispモードでC-M-x(eval-defun)からdeffaceを評価した場合は、eval-defunの特別な機能により、deffaceが何を指示するかをフェイスが正確に反映するように、そのフェイス上の任意のカスタムフェイスをオーバーライドする。

spec引数は、異なる種別の端末上でそのフェイスがどのような外観で表示されるべきかを示す、フェイスspecである。これは各要素が以下の形式であるようなalistであること

(display . plist)

displayは端末のクラス(以下参照)を指定する。plistは、そのような端末上でフェイスがどのような外観かを指定する、フェイス属性とその値からなるプロパティリストであること。後方互換性のために、(display plist)のように要素を記述することもできる。

specの要素のdisplayの部分は、その要素がマッチする端末を決定する。与えられた端末にたいして複数の要素がマッチした場合は、最初にマッチした要素がその端末にたいして使用される。displayには以下の3つが可能:

default

specのこの要素は、どの端末にもマッチしない。かわりにすべての端末に適用されるデフォルトを指定する。この要素が仕様された場合は、specの最初の要素でなければならない。この後の要素はこれらのデフォルトの一部、またはすべてをオーバーライドできる。

t

specのこの要素は、すべての端末にマッチする。したがってspecの後続要素が使用されることはない。通常tは、specの最後(または唯一)の要素として使用される。

リスト

displayがリストなら、各要素は(characteristic value…)という形式をもつこと。ここでcharacteristicは端末をクラス分けする方法、valueはdisplayに適用されるべき可能なクラス分類である。characteristicで利用可能な値は:

type: その端末が使用するウィンドウシステムの種類でgraphic(任意のグラフィック対応ディスプレイ)、x、pc(MS-DOSコンソール)、w32 (MS Windows 9X/NT/2K/XP)、またはtty(グラフィック非対応ディスプレイ)のいずれか。window-systemを参照のこと。
class: その端末がサポートするカラーの種類で、color、grayscale、またはmonoのいずれか。
background: バックグラウンドの種類でlightかdarkのいずれか。
min-colors: その端末がサポートするべき最小カラー数を表す整数。端末のdisplay-color-cellsの値が少なくとも指定された整数なら、その端末にマッチする。
supports: その端末がvalue…で与えられたフェイス属性を表示可能か否か(フェイスの属性を参照)。このテストがどのように行われるかについてのより正確な情報は、Display Face Attribute Testingを参照のこと。

与えられたcharacteristicにたいして、displayの要素が複数のvalueを指定する場合は、いずれの値も許容され得る。displayが複数の要素をもつ場合、各要素は異なるcharacteristicを指定すること。その端末のそれぞれのcharacteristicは、display内で指定された値のいずれか1つとマッチしなければならない。

たとえば以下は、標準フェイスhighlightの定義です:

(defface highlight
  '((((class color) (min-colors 88) (background light))
     :background "darkseagreen2")
    (((class color) (min-colors 88) (background dark))
     :background "darkolivegreen")
    (((class color) (min-colors 16) (background light))
     :background "darkseagreen2")
    (((class color) (min-colors 16) (background dark))
     :background "darkolivegreen")
    (((class color) (min-colors 8))
     :background "green" :foreground "black")
    (t :inverse-video t))
  "Basic face for highlighting."
  :group 'basic-faces)

内部的には、Emacsはフェイスのシンボルプロパティface-defface-spec内にそれぞれのフェイスのデフォルトspecを格納します(シンボルのプロパティを参照)。saved-faceプロパティは、カスタマイゼーションバッファーを使用してユーザーが保存した、任意のフェイスspecを格納します。customized-faceプロパティは、カレントセッションにたいしてカスタマイズされた保存されていないフェイスspecを格納します。そしてtheme-faceプロパティは、そのフェイスにたいするアクティブなカスタマイゼーションセッティングと、フェイスspecをもつCustomテーマを関連付けるalistです。そのフェイスのドキュメント文字列は、face-documentationプロパティ内に格納されます。

通常フェイスはdeffaceを使用して1回だけ宣言され、その外観にたいするそれ以上の変更はCustomizeフレームワーク(Customizeユーザーインターフェース、またはcustom-set-faces関数を通じて。カスタマイズの適用を参照されたい)、またはフェイスリマッピング(フェイスのリマップを参照)により行われます。Lispから触接フェイスspec変更を要する稀な機会では、face-spec-set関数を使用できます。

Function: face-spec-set face spec &optional spec-type

この関数は、faceにたいするフェイスspecとして、specを適用する。specは、上述したdeffaceにたいするフェイスspecであること。

この関数は、もしそれが既存のものでなければ、有効なフェイス名としてfaceを定義して、既存フレームのその属性を(再)計算することも行う。

The optional argument spec-type determines which spec to set. If it is omitted or nil or face-override-spec, this function sets the override spec, which overrides face specs on face of all the other types mentioned below. This is useful when calling this function outside of Custom code. If spec-type is customized-face or saved-face, this function sets the customized spec or the saved custom spec, respectively. If it is face-defface-spec, this function sets the default face spec (the same one set by defface). If it is reset, this function clears out all customization specs and override specs from face (in this case, the value of spec is ignored). The effect of any other value of spec-type on the face specs is reserved for internal use, but the function will still define face itself and recalculate its attributes, as described above.

39.12.3 フェイス属性のための関数

このセクションでは、名前つきフェイスの属性に直接アクセスしたり、変更する関数を説明します。

Function: face-attribute face attribute &optional frame inherit

この関数は、frame上のfaceにたいする、属性attributeの値をリターンする。

If frame is omitted or nil, that means the selected frame (see section 入力のフォーカス). If frame is t, this function returns the value of the specified attribute for newly-created frames (this is normally unspecified, unless you have specified some value using set-face-attribute; see below).

inheritがnilなら、faceにより定義される属性だけが考慮されるので、リターンされる値はunspecified、または相対的な値かもしれない。inheritが非nilなら、faceのattributeの定義が、:inherit属性で指定されたフェイスとマージされる。しかしリターンされる値は依然としてunspecified、または相対的な値かもしれない。inheritがフェイス、またはフェイスのリストなら、指定された絶対的な値になるまで、結果はそのフェイス(1つ以上)と更にマージされる。

リターン値が指定されていて、かつ絶対的であることを保証するためには、inheritにたいしてdefaultの値を使用すること。(常に完全に指定される)defaultフェイスとマージすることにより、すべての未指定または相対的な値は解決されるだろう。

たとえば

(face-attribute 'bold :weight)
     ⇒ bold

Function: face-attribute-relative-p attribute value

この関数はvalueがフェイス属性attributeの値として使用された際に相対的なら、非nilをリターンする。This function returns non- if , when used as the value of the face attribute , is relative.これはフェイスリスト内の後続のフェイス、または継承した他のフェイスが由来となる、任意の値で完全にオーバーライドするのではなく、変更されるであろうことを意味する。

すべての属性にたいして、unspecifiedは相対的な値である。:heightにたいしては、浮動小数点数と関数値も相対的である。

たとえば:

(face-attribute-relative-p :height 2.0)
     ⇒ t

Function: face-all-attributes face &optional frame: この関数は、faceの属性のalistをリターンする。結果の要素は、(attr-name . attr-value)という形式の、名前/値ペアーである。オプション引数frameは、リターンするべきfaceの定義をもつフレームを指定する。省略またはnilなら、リターン値には新たに作成されるフレームにたいする、faceのデフォルト属性が記述される。

Function: merge-face-attribute attribute value1 value2: value1がフェイス属性attributeにたいして相対的な値なら、基礎的な値value2とマージしてリターンする。それ以外の場合、value1がフェイス属性attributeにたいして絶対的な値なら、value1を変更せずにリターンする。

通常、Emacsは各フレームのフェイス属性を自動的に計算するために、各フェイスのフェイスspecを使用します(フェイスの定義を参照)。関数set-face-attributeは、特定またはすべてのフレームのフェイスに直接属性を割り当てることにより、この計算をオーバーライドできます。この関数は主として、内部的な使用を意図したものです。

Function: set-face-attribute face frame &rest arguments

この関数は、frameにたいするfaceの1つ以上の属性をセットする。この方法で指定された属性は、faceに属するフェイスspec(1つ以上)をオーバーライドする。

余分の引数argumentsは、セットするべき属性と、それらの値を指定する。これらは、(:familyや:underlineのような)属性名と、値が交互になるよう構成されていること。すなわち、

(set-face-attribute 'foo nil :weight 'bold :slant 'italic)

これは属性:weightをbold、.属性:slantをitalicにセットする。

frameがtなら、この関数は新たに作成されるフレームにたいする、デフォルト属性をセットする。frameがnilなら、この関数はすべての既存フレーム、同様に新たに作成されるフレームにたいして、その属性をセットする。

The following commands and functions mostly provide compatibility with old versions of Emacs. They work by calling set-face-attribute. Values of t and nil (or omitted) for their frame argument are handled just like set-face-attribute and face-attribute. The commands read their arguments using the minibuffer, if called interactively.

Command: set-face-foreground face color &optional frame
Command: set-face-background face color &optional frame: これらはそれぞれfaceの:foreground属性、または:background属性にcolorをセットする。

Command: set-face-stipple face pattern &optional frame: これはfaceの:stipple属性に、patternをセットする。

Command: set-face-font face font &optional frame: これはfaceの:font属性に、fontをセットする。

Function: set-face-bold face bold-p &optional frame: これはfaceの:weight属性にたいして、bold-pがnilならnormal、それ以外ならboldをセットする。

Function: set-face-italic face italic-p &optional frame: これはfaceの:slant属性にたいして、italic-pがnilならnormal、それ以外ならitalicをセットする。

Command: set-face-underline face underline &optional frame: これはfaceの:underline属性に、underlineをセットする。

Command: set-face-inverse-video face inverse-video-p &optional frame: これはfaceの:inverse-video属性に、inverse-video-pをセットする。

Command: invert-face face &optional frame: これはフェイスfaceのフォアグラウンドカラーとバックグラウンドカラーを交換する。

以下は、フェイスの属性を調べる関数です。これらは主として、古いバージョンのEmacsとの互換性のために提供されます。これらにたいしてframeを指定しなければ選択されたフレームを、tなら新たなフレームにたいするデフォルトデータを参照します。フェイスがその属性にたいして何の値も定義していなければ、unspecifiedがリターンされます。inheritがnilなら、そのフェイスにより直接定義された属性だけがリターンされます。inheritが非nilなら、そのフェイスの:inherit属性により指定される任意のフェイスを、inheritがフェイスまたはフェイスのリストなら、指定された属性が見つかるまで、それらも考慮されます。リターンされる値が常に指定された値であることを保証するためには、inheritにたいして値defaultを使用してください。

Function: face-font face &optional frame character

この関数は、フェイスfaceのフォント名をリターンする。

If the optional argument frame is specified, it returns the name of the font of face for that frame. If frame is omitted or nil, the selected frame is used. And, in this case, if the optional third argument character is supplied, it returns the font name used for character.

Function: face-foreground face &optional frame inherit
Function: face-background face &optional frame inherit: These functions return the foreground color (or background color, respectively) of face face, as a string. If the color is unspecified, they return nil.

Function: face-stipple face &optional frame inherit: この関数は、フェイスfaceのバックグラウンド点描パターンの名前、もしなければnilをリターンする。

Function: face-bold-p face &optional frame inherit: この関数はfaceの:weight属性がnormalよりbold寄り(semi-bold、bold、 extra-bold、ultra-boldのいずれか)なら、非nil、それ以外ならnilをリターンする。

Function: face-italic-p face &optional frame inherit: この関数は、faceの:slant属性がitalicかobliqueなら非nil、それ以外ならnilをリターンする。

Function: face-underline-p face &optional frame inherit: この関数は、フェイスfaceが非nilの:underline属性を指定する場合は、非nilをリターンする。

Function: face-inverse-video-p face &optional frame inherit: この関数は、フェイスfaceが非nilの:inverse-video属性を指定する場合は、非nilをリターンする。

39.12.4 フェイスの表示

Emacsが与えられたテキスト断片を表示する際、そのテキストの視覚的外観は異なるソースから描画されるフェイスにより決定されるかもしれません。これら種々のソースが、特定の文字にいたいして複数のフェイスを指定する場合、Emacsはそれらのさまざまなフェイスの属性をマージします。以下に、Emacsがフェイスをマージする順序を優先度順に記します:

そのテキストが特別なグリフで構成される場合、そのグリフは特定のフェイスを指定できる。グリフを参照のこと。
アクティブなリージョンにテキストがある場合、Emacsはregionフェイスを使用してそれをハイライトする。Standard Faces in The GNU Emacs Manualを参照のこと。
If the text lies within an overlay with a non-nil face property, Emacs applies the face(s) specified by that property. If the overlay has a mouse-face property and the mouse is near enough to the overlay, Emacs applies the face or face attributes specified by the mouse-face property instead. See section オーバーレイのプロパティ.
1つの文字を複数のオーバーレイがカバーする場合は、高優先度のオーバーレイが低優先度のオーバーレイをオーバーライドする。オーバーレイを参照のこと。
そのテキストがfaceまたはmouse-faceプロパティを含む場合、Emacsは指定されたフェイスおよびフェイス属性を適用する。特殊な意味をもつプロパティを参照のこと(これはFont Lockモードのフェイス適用方法である。Font Lockモードを参照されたい)。
そのテキストが選択されたウィンドウのモードラインにある場合、Emacsはmode-lineフェイスを適用する。選択されていないウィンドウのモードラインでは、Emacsはmode-line-inactiveフェイスを使用する。ヘッダーラインにたいしては、Emacsはheader-lineフェイスを適用する。
If the text comes from an overlay string via before-string or after-string properties (see section オーバーレイのプロパティ), or from a display string (see section その他のディスプレー仕様), and the string doesn’t contain a face or mouse-face property, but the buffer text affected by the overlay/display property does define a face, Emacs applies the face attributes of the “underlying” buffer text. Note that this is so even if the overlay or display string is displayed in the display margins (see section マージン内への表示).
先行ステップの間に、与えられた属性が指定されなければ、Emacsはdefaultフェイスの属性を適用する。

各ステージにおいて、フェイスが有効な:inherit属性をもつ場合、Emacsは値unspecifiedをもつすべての属性が、親フェイス(1つ以上)由来で描画される、対応する値をもつものとして扱います。フェイスの属性を参照してください。親フェイスでも、属性がunspecifiedのままかもしれないことに注意してください。その場合には、フェイスマージの次レベルでも、その属性はunspecifiedのままです。

39.12.5 フェイスのリマップ

変数face-remapping-alistは、あるフェイスの外観のバッファーローカル、またはグローバルな変更にたいして使用されます。たとえばこれは、text-scale-adjustコマンド(Text Scale in The GNU Emacs Manualを参照)の実装に使用されています。

Variable: face-remapping-alist

この変数の値は、要素が(face . remapping)という形式をもつalistである。これによりEmacsは、フェイスfaceをもつ任意のテキストを、通常のfaceの定義ではなく、remappingで表示する。

remappingには、テキストプロパティfaceにたいして適切な任意のフェイスspec、すなわちフェイス(フェイス名または属性/値ペアーのプロパティリスト)、またはフェイスのリストのいずれかを指定できる。詳細は、特殊な意味をもつプロパティのfaceテキストプロパティの記述を参照のこと。remappingはリマップされるフェイスにたいる、完全な仕様としての役目をもつ。これは通常のfaceを変更せずに置き換える。

face-remapping-alistがバッファーローカルなら、そのローカル値はそのバッファーでのみ効果をもつ。

注意: フェイスのリマッピングは再帰的ではない。remappingが同じフェイス名faceを参照する場合、直接またはremapping内の他の何らかのフェイスの:inherit属性を通じて、その参照はfaceの通常の定義を使用する。たとえばmode-lineフェイスが、face-remapping-alist内の以下のエントリーでリマップされる場合:

(mode-line italic mode-line)

mode-lineフェイスの新たな定義はitalicフェイス、および(リマップされていない)通常のmode-lineフェイスの定義から継承される。

The following functions implement a higher-level interface to face-remapping-alist. Most Lisp code should use these functions instead of setting face-remapping-alist directly, to avoid trampling on remappings applied elsewhere. These functions are intended for buffer-local remappings, so they all make face-remapping-alist buffer-local as a side-effect. They manage face-remapping-alist entries of the form

  (face relative-spec-1 relative-spec-2 ... base-spec)

上述したように、relative-spec-Nとbase-specはそれぞれ、フェイス名または属性/値ペアーのプロパティリストです。相対的リマッピング(relative remapping)エントリーrelative-spec-Nはそれぞれ、face-remap-add-relativeおよびface-remap-remove-relative関数により管理されます。これらはテキストサイズ変更のような、単純な変更を意図しています。ベースリマッピング(base remapping)エントリーbase-specは最低の優先度をもち、face-remap-set-baseおよびface-remap-reset-base関数により管理されます。これは、メジャーモードが制御下のバッファーでフェイスをリマップするために用いることを意図しています。

Function: face-remap-add-relative face &rest specs

この関数は、カレントバッファー内のフェイスfaceにたいして、相対的リマッピングとして、specs内にフェイスspecを追加する。残りの引数specsはフェイス名のリスト、または属性/値ペアーのプロパティリストという、いずれかの形式であること。

The return value is a Lisp object that serves as a cookie; you can pass this object as an argument to face-remap-remove-relative if you need to remove the remapping later.

;; Remap the 'escape-glyph' face into a combination
;; of the 'highlight' and 'italic' faces:
(face-remap-add-relative 'escape-glyph 'highlight 'italic)

;; Increase the size of the 'default' face by 50%:
(face-remap-add-relative 'default :height 1.5)

Function: face-remap-remove-relative cookie: この関数は、以前face-remap-add-relativeで追加された相対的リマッピングを削除する。cookieは、そのリマッピングが追加されたときに、face-remap-add-relativeがリターンしたLispオブジェクトであること。

Function: face-remap-set-base face &rest specs

この関数は、カレントバッファー内のfaceのベースリマッピングを、specsにセットする。specsが空なら、face-remap-reset-base(以下参照)を呼び出したように、デフォルトベースリマッピングがリストアされる。これは単一の値nilを含むspecsとは異なることに注意。これは逆の結果をもたらす(faceのグローバル定義は無視される)。

これは、グローバルなフェイス定義を継承した、デフォルトのbase-specを上書きするので、必要ならそのような継承を追加するのは呼び出し側の責任である。

Function: face-remap-reset-base face: この関数は、faceのベースリマッピングに、faceのグローバル定義から継承した、デフォルト値にセットする。

39.12.6 フェイスを処理するための関数

以下はフェイスを作成および処理するための、追加の関数です。

Function: face-list: この関数は、すべての定義済みフェイス名のリストをリターンする。

Function: face-id face: この関数は、フェイスfaceのフェイス番号(face number)をリターンする。これはEmacs内の低レベルで、フェイスを一意に識別する番号である。フェイス番号によるフェイス参照を要するのは稀である。

Function: face-documentation face: この関数は、フェイスfaceのドキュメント文字列、それが指定されていなければnilをリターンする。

Function: face-equal face1 face2 &optional frame: これは、フェイスface1とフェイスface2が、表示にたいして同じ属性をもつならtをリターンする。

Function: face-differs-from-default-p face &optional frame: これはフェイスfaceの表示がデフォルトフェイスと異なるなら、非nilをリターンする。

フェイスエイリアス(face alias)は、あるフェイスにたいして等価な名前を提供します。エイリアスシンボルのface-aliasプロパティに対象となるフェイス名を与えることにより、フェイスエイリアスを定義できます。以下の例では、mode-lineフェイスにたいするエイリアスとして、modelineを作成します。

(put 'modeline 'face-alias 'mode-line)

Macro: define-obsolete-face-alias obsolete-face current-face when: このマクロは、current-faceのエイリアスとしてobsolete-faceを定義するとともに、将来に削除されるかもしれないことを示すためにobsolete(時代遅れ)とマークする。whenは、obsolete-faceがobsoleteになる時期を示す文字列(通常はバージョン番号文字列)であること。

39.12.7 フェイスの自動割り当て

以下のフックは、バッファー内のテキストに自動的にフェイスを割り当てるために使用されます。これはJit-Lockモードの実装の一部であり、Font-Lockにより使用されます。

Variable: fontification-functions

この変数は、再表示を行う直前に、Emacsの再表示により呼び出される関数のリストを保持する。これらはFont Lockが有効でないときでも呼び出される。Font Lockモードが有効なら、この変数は通常は単一の関数jit-lock-functionだけを保持する。

関数は、バッファー位置posを単一の引数として、リストされた順に呼び出される。これらは、カレントバッファー内のposで開始されるテキストにたいして、集合的にフェイスの割り当てを試みるべきである。

関数はfaceプロパティをセットするおとにより、割り当てるフェイスを記録すること。またフェイスを割り当てたすべてのテキストに、非nilのfontifiedプロパティも追加するべきである。このプロパティは再表示に、そのテキストにたいしてそのフェイスがすでに割り当て済みであることを告げる。

posの後の文字がすでに非nilのfontifiedプロパティをもつが、フォント表示化を要さない場合に、何も行わない関数を追加するのは、おそらくよいアイデアである。ある関数が、前の関数による割り当てをオーバーライドする場合には、実際に問題となるのは最後の関数終了後のプロパティである。

効率化のために、通常は各呼び出しにおいて400から600前後の文字にフェイスを割り当てるように、これらの関数を記述することを推奨する。

39.12.8 基本的なフェイス

If your Emacs Lisp program needs to assign some faces to text, it is often a good idea to use certain existing faces or inherit from them, rather than defining entirely new faces. This way, if other users have customized the basic faces to give Emacs a certain look, your program will fit in without additional customization.

以下にEmacsが定義する基本フェイスのいくつかをリストしました。これらに加えて、ハイライトがFont Lockモードによりまだ処理されていなかったり、いくつかのFont Lockフェイスが使用されていなければ、構文的ハイライトのために、Font Lockフェイスを使うようにしたいと思うかもしれません。Font Lockのためのフェイスを参照してください。

default: 属性がすべて指定されたデフォルトフェイス。他のすべてのフェイスは、暗にこのフェイスを継承する。未指定(unspecified)な任意の属性は、このフェイスの属性をデフォルトとする(フェイスの属性を参照)。
bold
italic
bold-italic
underline
fixed-pitch
fixed-pitch-serif
variable-pitch: これらは、名前に示されるような属性をもち(boldはboldの:weight属性をもつ)、それ以外のすべての属性は未指定である(そのためdefaultにより与えられる)。
shadow: For dimmed-out text. For example, it is used for the ignored part of a filename in the minibuffer (see Minibuffers for File Names in The GNU Emacs Manual).
link
link-visited: For clickable text buttons that send the user to a different buffer or location.
highlight: 一時的に強調するべきテキスト範囲用。たとえば一般的に、カーソルのハイライトにはmouse-faceプロパティが割り当てられる(特殊な意味をもつプロパティを参照)。
match
isearch
lazy-highlight: For text matching (respectively) permanent search matches, interactive search matches, and lazy highlighting other matches than the current interactive one.
error
warning
success: エラー、警告、成功に関するテキスト用。たとえば*Compilation*内のメッセージにたいして使用される。

39.12.9 フォントの選択

Emacsがグラフィカルなディスプレイ上で文字を描画可能になる前に、まずその文字にたいするフォント(font)を選択しなければなりません²⁰。Fonts in The GNU Emacs Manualを参照してください。通常、Emacsはその文字に割り当てられたフェイス、特にフェイス属性:family、:weight、:slant、:width(フェイスの属性を参照)にもとづいて、自動的にフォントを選択します。フォントの選択は、表示される文字にも依存します。表示できるのは文字セットが限定されているフォントもいくつかあります。利用可能なフォントがこの要件を完全に満たさない場合、Emacsはもっとも近いフォント(closest matching font)を探します。このセクション内の変数は、Emacsがこの選択を行う方法を制御します。

User Option: face-font-family-alternatives

あるfamilyが指定されたが存在しない場合、この変数は試みるべき代替えのフォントファミリーを指定する。各要素は以下の形式をもつ:

(family alternate-families…)

familyが指定されたが利用できなければ、Emacsはalternate-familiesで与えられるファミリーで存在するものが見つかるまで、1つずつファミリーを試みる。

User Option: face-font-selection-order

希望するすべてのフェイス属性(:width、:height、:weight、:slant)に完全にマッチするフォントが存在しない場合、この変数はもっとも近いフォントの選択時に考慮すべき、これらの属性の順序を指定する。値はこれらの属性シンボルを重要度降順で含むリストであること。デフォルトは(:width :height :weight :slant)。

フォント選択はまず、このリスト内の最初の属性にたいして利用可能な最適マッチを探す。その後、この方法で最適なフォントの中から、2つ目の属性にたいして最適なマッチを検索、...のように選択を行う。

属性:weightおよび:widthは、normalを中心とする範囲のような、シンボリック値をもつ。より極端(normalから離れた)なマッチは、より極端ではない(normalに近い)マッチより、幾分優先される。これは、可能なかぎり非normalなフェイスが、normalなフェイスとは対照的になることを保証するようにデザインされている。

この変数が違いを生むケースの例は、デフォルトフォントに等価なイタリックがない場合である。デフォルトの順では、italicフェイスは、デフォルトのフォントに類似した非イタリックのフォントを使用するだろう。しかし:heightの前に:slantを置くと、italicフェイスはたとえheightが同じでなくとも、イタリックフォントを使用するだろう。

User Option: face-font-registry-alternatives

この変数は、registryが指定されたがそれが存在しない場合に試みるべき、代替えのフォントレジストリーを指定する。各要素は以下の形式をもつ:

(registry alternate-registries…)

registryが指定されたが利用できなければ、Emacsはalternate-registries内で存在するレジストリーが見つかるまで、他のレジストリーを1つずつ試みる。

Emacsがスケーラブルフォントを使用するようにできますが、デフォルトではそれらを使用しないようになっています。

User Option: scalable-fonts-allowed

この変数は、どのスケーラブルフォントを使用するかを制御する。値nil(デフォルト)は、スケーラブルフォントを使用しないことを意味する。tはそのテキストにたいして適切と思われる、任意のスケーラブルフォントを使用することを意味する。

それ以外なら、値は正規表現のリストであること。その場合、名前がこのリスト内の正規表現にマッチする、任意のスケーラブルフォントの使用が有効になる。たとえば、

(setq scalable-fonts-allowed '("iso10646-1$"))

これは、レジストリーがiso10646-1のようなスケーラブルフォントの使用を可能にする。

Variable: face-font-rescale-alist

この変数は、特定のフォントにたいするスケーリングを指定する。値は、以下の形式の要素をもつリストであること

(fontname-regexp . scale-factor)

使用しようとするフォントの名前がfontname-regexpにマッチする場合、これはファクターscale-factorに対応した、同様な大きさのフォントの選択を指示する。特定のフォントが提示する通常のheightやwidthが大きい、または小さい場合に、フォントサイズを正規化するためにこの機能を使用できるだろう。

39.12.10 フォントの照会

Function: x-list-fonts name &optional reference-face frame maximum width

This function returns a list of available font names that match name. name should be a string containing a font name in either the Fontconfig, GTK+, or XLFD format (see Fonts in The GNU Emacs Manual). Within an XLFD string, wildcard characters may be used: the ‘*’ character matches any substring, and the ‘?’ character matches any single character. Case is ignored when matching font names.

オプション引数reference-faceおよびframeが指定された場合は、リターンされるリストにはその時点でフレームframe上でのreference-face(フェイス名)と同じサイズのフォントだけが含まれる。

オプション引数maximumは、リターンされるフォント数の制限をセットする。これが非nilなら、リターン値は最初にマッチしたmaximum個のフォントの後が切り捨てられる。maximumに小さい値を指定すれば、そのパターンに多くのフォントがマッチするような場合に、この関数をより高速にできる。

オプション引数widthは、希望するフォントの幅を指定する。これが非nilなら、この関数は文字の幅(平均)が、reference-faceのwidth倍の幅であるようなフォントだけをリターンする。

Function: x-family-fonts &optional family frame

この関数は、frame上のファミリーfamilyにたいして利用可能なフォントを記述するリストをリターンする。familyが省略またはnilなら、このリストはすべてのファミリーに適用され、すなわち利用可能なすべてのフォントを含む。それ以外なら、familyは文字列であること。これにはワイルドカード‘?’と‘*’を含めることができる。

このリストは、frameのあるディスプレイを記述する。frameが省略またはnilなら、これは選択されたフレームのディスプレイに適用される(入力のフォーカスを参照)。

このリスト内の各要素は、以下の形式のベクターであること:

[family width point-size weight slant
 fixed-p full registry-and-encoding]

最初の5つの要素はフェイス属性に対応する。あるフェイスにたいしてこれらの属性を指定した場合は、このフォントが使用されるだろう。

最後の3つの要素は、そのフォントに関する追加の情報を与える。そのフォントが固定ピッチ(fixed-pitch)でなければ、fixed-pは非nilである。fullはそのフォントのフルネーム、registry-and-encodingはそのフォントのレジストリーとエンコーディングを与える。

39.12.11 フォントセット

A fontset is a list of fonts, each assigned to a range of character codes. An individual font cannot display the whole range of characters that Emacs supports, but a fontset can. Fontsets have names, just as fonts do, and you can use a fontset name in place of a font name when you specify the font for a frame or a face. Here is information about defining a fontset under Lisp program control.

Function: create-fontset-from-fontset-spec fontset-spec &optional style-variant-p noerror

この関数は、仕様文字列fontset-specに応じて、新たなフォントセットを定義する。この文字列は以下のような形式であること:

fontpattern, [charset:font]…

カンマの前後の空白文字は無視される。

この文字列の最初の部分fontpatternは、最後の2つのフィールドが‘fontset-alias’であることを除外して、標準Xフォント名形式をもつこと。

新たなフォントセットはlong名とshort名という、2つの名前をもつ。long名は、それ全体がfontpatternであり、short名は‘fontset-alias’である。いずれの名前でもこのフォントセットを参照できる。同じ名前がすでに存在するフォントセットでは、noerrorがnilならエラーがシグナルされ、noerrorが非nilならこの関数は何も行わない。

オプション引数style-variant-pが非nilなら、そのフォントセットのbold、italic、およびbold-italicも同様に作成するよう指示する。これらの変種フォントセットはshort名をもたず、bold、および/またはitalicを示すようにfontpatternを変更して作成したlong名だけをもつ。

仕様文字列は、そのフォントセット内でどのフォントを使用するかも宣言する。詳細は以下を参照。

構成‘charset:font’は、ある特定の文字セットにたいして、(このフォントセット内の)どのフォントを使用するかを指定します。ここでcharsetは文字セットの名前、fontはその文字セットにたいして使用するフォントです。仕様文字列内で、この構成を任意の回数使用できます。

明示的に指定しなかった残りの文字セットにたいして、Emacsはfontpatternにもとづきフォントを選択します。これは‘fontset-alias’を、その文字セットを命名する値に置き換えます。文字セットASCIIにたいしては、‘fontset-alias’は‘ISO8859-1’に置き換えられます。

加えて、後続の複数フィールドがワイルドカードなら、Emacsはそれらを1つのワイルドカードにまとめます。これは自動スケールフォント(auto-scaled fonts)の使用を防ぐためです。フォントを大きくスケーリングすることにより作成されたフォントは編集に使用できず、小さくスケーリングされたフォントは、それ自身のサイズがより小さいフォントを使用する(Emacsが行う方法)ほうがよいので、有用ではありません。

つまり、以下のようなfontpatternなら

-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24

ASCIIにたいするフォントspecは、以下のようになるでしょう:

-*-fixed-medium-r-normal-*-24-*-ISO8859-1

また、Chinese GB2312文字にたいするフォントspecは、以下のようになるでしょう:

-*-fixed-medium-r-normal-*-24-*-gb2312*-*

上記のフォントspecにマッチするChineseフォントをもっていないかもしれません。ほとんどのXディストリビューションには、familyフィールドに‘song ti’か‘fangsong ti’をもつChineseフォントだけが含まれます。そのような場合には、以下のように‘Fontset-n’を指定できます:

Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
        chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*

この場合、Chinese GB2312以外のすべての文にたいするフォントspecはfamilyフィールドに‘fixed’をもち、Chinese GB2312にたいするフォントspecはfamilyフィールドにワイルドカード‘*’をもちます。

Function: set-fontset-font name character font-spec &optional frame add

This function modifies the existing fontset name to use the font matching with font-spec for the specified character.

nameがnilなら、この関数はframeのフォントセット、frameがnilなら選択されたフレームのフォントセットを変更する。

nameがtなら、この関数はshort名が‘fontset-default’であるような、デフォルトフォントセットを変更する。

In addition to specifying a single codepoint, character may be a cons (from . to), where from and to are character codepoints. In that case, use font-spec for all the characters in the range from and to (inclusive).

characterには文字セットも指定できる。この場合は、その文字セット内のすべての文字にたいして、font-specを使用する。

characterにはスクリプト名も指定できる。この場合は、その文字セット内のすべての文字にたいして、font-specを使用する。

font-spec may be a font-spec object created by the function font-spec (see section 低レベルのフォント表現).

font-specにはコンス(family . registry)を指定できる。ここでfamilyはフォントのファミリー名(先頭にfoundry名が含まれるかもしれない)、registryはフォントのレジストリー名(末尾にエンコーディング名が含まれるかもしれない)である。

font-specには、フォント名文字列も指定できる。

font-spec may be nil, which explicitly specifies that there’s no font for the specified character. This is useful, for example, to avoid expensive system-wide search for fonts for characters that have no glyphs, like those from the Unicode Private Use Area (PUA).

オプション引数addが非nilなら、以前セットされたフォントspecにfont-specを追加する方法を指定する。prependならfont-specは先頭に、appendならfont-specは末尾に追加される。デフォルトでは、font-specは以前のセッティングをオーバーライドする。

たとえば、以下は文字セットjapanese-jisx0208に属するすえての文字にたいして、ファミリー名が‘Kochi Gothic’であるようなフォントを使用するように、デフォルトフォントセットを変更する。

(set-fontset-font t 'japanese-jisx0208
                  (font-spec :family "Kochi Gothic"))

Function: char-displayable-p char

この関数は、Emacsがcharを表示できるべきなら、tをリターンする。より正確には、選択されたフレームのフォントセットが、charが属する文字セットを表示するためのフォントをもつ場合は、tをリターンする。

フォントセットは、文字単位でフォントを指定できる。フォントセットがこれを行う場合、この関数の値は正確ではないかもしれない。

39.12.12 低レベルのフォント表現

通常は、フォントを直接扱う必要はありません。これを行う必要がある場合には、このセクションでその方法を説明します。

Emacs Lispでは、フォントはフォントオブジェクト(font objects)、フォントspec(font specs)、フォントエンティティー(font entities)という、3つの異なるLispオブジェクトを使用して表現されます。

Function: fontp object &optional type

objectがフォントオブジェクト、フォントspec、フォントエンティティーならt、それ以外ならnilをリターンする。

オプション引数typeが非nilなら、チェックするLispオブジェクトの正確なタイプを決定する。この場合、typeはfont-object、font-spec、font-entityのいずれかであること。

フォントオブジェクトは、Emacsがオープンしたフォントを表します。Lispでフォントオブジェクトは変更できませんが、調べることはできます。

Function: font-at position &optional window string: ウィンドウwindow内の位置positionにある文字を表示するために使用されている、フォントオブジェクトをリターンする。windowがnilの場合のデフォルトは、選択されたウィンドウである。stringがnilなら、positionはカレントバッファー内の位置を指定する。それ以外なら、stringは文字列で、positionはその文字列内での位置を指定すること。

フォントspecは、フォントを探すために使用できる仕様セットを含むLispオブジェクトです。フォントspec内の仕様にたいして、1つ以上のフォントがマッチすることができます。

Function: font-spec &rest arguments

arguments内の仕様を使用して、新たなフォントspecをリターンする。これはproperty-valueのペアーであること。可能な仕様は以下のとおり:

:name

The font name (a string), in either XLFD, Fontconfig, or GTK+ format. See Fonts in The GNU Emacs Manual.

:family

:foundry

:weight

:slant

:width

これらは、同名のフェイス属性と同じ意味をもつ。フェイスの属性を参照のこと。

:size

フォントサイズ。非負の整数はピクセル単位、浮動小数点数ならポイントサイズを指定する。

:adstyle

‘sans’のように、そのフォントにたいするタイポグラフィックスタイル(typographic style)の追加情報。値は文字列またはシンボルであること。

:registry

‘iso8859-1’のような、フォントの文字セットレジストリーとエンコーディング。値は文字列またはシンボルであること。

:script

そのフォントがサポートしなければならないスクリプト(シンボル)。

:lang

The language that the font should support. The value should be a symbol whose name is a two-letter ISO-639 language name. On X, the value is matched against the “Additional Style” field of the XLFD name of a font, if it is non-empty. On MS-Windows, fonts matching the spec are required to support codepages needed for the language. Currently, only a small set of CJK languages is supported with this property: ‘ja’, ‘ko’, and ‘zh’.

:otf

The font must be an OpenType font that supports these OpenType features, provided Emacs is compiled with a library, such as ‘libotf’ on GNU/Linux, that supports complex text layout for scripts which need that. The value must be a list of the form

(script-tag langsys-tag gsub gpos)

ここでscript-tagはOpenTypeスクリプトタグシンボル、langsys-tagはOpenType言語システムタグシンボル(nilならデフォルト言語システムを使用)、gsubはOpenType GSUB機能タグシンボル(何も要求されない場合はnil)、gposはOpenType GPOS機能タグシンボルのリスト(何も要求されない場合はnil)である。gsubまたはgposがリストなら、そのリスト内のnil要素は、そのフォントが残りすべてのタグシンボルにマッチしてはならないことを意味する。gposは省略することができる。

Function: font-put font-spec property value: フォントspec font-spec内のプロパティpropertyに、valueをセットする。

フォントエンティティーは、オープンする必要がないフォントへの参照です。フォントオブジェクトとフォントspecの中間的な性質をもち、フォントspecとは異なり、フォントオブジェクトと同様、単一かつ特定のフォントを参照します。フォントオブジェクトとは異なり、フォントエンティティーの作成では、そのフォントのコンテンツはコンピューターへのメモリーにロードされません。Emacsは、スケーラブルフォントを参照するために単一のフォントエンティティーから、複数の異なるサイズのフォントオブジェクトをオープンするかもしれません。

Function: find-font font-spec &optional frame: この関数は、フレームframe上のフォントspec font-specにもっともマッチするフォントエンティティーをリターンする。frameがnilの場合のデフォルトは、選択されたフレームである。

Function: list-fonts font-spec &optional frame num prefer

この関数は、フォントspec font-specにマッチする、すべてのフォントエンティティーのリストをリターンする。

The optional argument frame, if non-nil, specifies the frame on which the fonts are to be displayed. The optional argument num, if non-nil, should be an integer that specifies the maximum length of the returned list. The optional argument prefer, if non-nil, should be another font spec, which is used to control the order of the returned list; the returned font entities are sorted in order of decreasing closeness to that font spec.

If you call set-face-attribute and pass a font spec, font entity, or font name string as the value of the :font attribute, Emacs opens the best matching font that is available for display. It then stores the corresponding font object as the actual value of the :font attribute for that face.

以下の関数は、フォントに関する情報を取得するために使用できます。これらの関数のfont引数にはフォントオブジェクト、フォントエンティティー、またはフォントspecを指定できます。

Function: font-get font property

この関数は、fontにたいするフォントプロパティpropertyの値をリターンする。

fontがフォントspecで、そのフォントspecがpropertyを指定しなければ、リターン値はnilである。fontがフォントオブジェクト、またはフォントエンティティーなら、:scriptプロパティにたいする値は、そのフォントがサポートするスクリプトのリストかもしれない。

Function: font-face-attributes font &optional frame

この関数は、fontに対応するフェイス属性のリストをリターンする。オプション引数frameは、そのフォントが表示されるフレームを指定する。これがnilなら、選択されたフレームが使用される。リターン値は以下の形式である

(:family family :height height :weight weight
   :slant slant :width width)

ここでfamily、height、weight、slant、widthの値は、フェイス属性の値である。fontにより指定されない場合いくつかのキー/属性ペアーは、このリストから省略されるかもしれない。

Function: font-xlfd-name font &optional fold-wildcards

この関数は、fontにマッチするXLFD((X Logical Font Descriptor))を文字列としてリターンする。XLFDに関する情報は、Fonts in The GNU Emacs Manualを参照のこと。その名前がXLFD(最大255文字を含むことが可能)にたいして長すぎる場合、この関数はnilをリターンする。

オプション引数fold-wildcardsが非nilなら、連続するワイルドカードは1つにまとめられる。

The following two functions return important information about a font.

Function: font-info name &optional frame

This function returns information about a font specified by its name, a string, as it is used on frame. If frame is omitted or nil, it defaults to the selected frame.

The value returned by the function is a vector of the form [opened-name full-name size height baseline-offset relative-compose default-ascent max-width ascent descent space-width average-width filename capability]. Here’s the description of each components of this vector:

opened-name: The name used to open the font, a string.
full-name: The full name of the font, a string.
size: The pixel size of the font.
height: The height of the font in pixels.
baseline-offset: The offset in pixels from the ASCII baseline, positive upward.
relative-compose
default-ascent: Numbers controlling how to compose characters.
ascent
descent: The ascent and descent of this font. The sum of these two numbers should be equal to the value of height above.
space-width: The width, in pixels, of the font’s space character.
average-width: The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.
filename: The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font’s file name.
capability: A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the GSUB and GPOS features supported by the font. Each of these elements is a list of the form ((script (langsys feature …) …) …), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

Function: query-font font-object

This function returns information about a font-object. (This is in contrast to font-info, which takes the font name, a string, as its argument.)

The value returned by the function is a vector of the form [name filename pixel-size max-width ascent descent space-width average-width capability]. Here’s the description of each components of this vector:

name: The font name, a string.
filename: The file name of the font as a string. This can be nil if the font back-end does not provide a way to find out the font’s file name.
pixel-size: The pixel size of the font used to open the font.
max-width: The maximum advance width of the font.
ascent
descent: The ascent and descent of this font. The sum of these two numbers gives the font height.
space-width: The width, in pixels, of the font’s space character.
average-width: The average width of the font characters. If this is zero, Emacs uses the value of space-width instead, when it calculates text layout on display.
capability: A list whose first element is a symbol representing the font type, one of x, opentype, truetype, type1, pcf, or bdf. For OpenType fonts, the list includes 2 additional elements describing the GSUB and GPOS features supported by the font. Each of these elements is a list of the form ((script (langsys feature …) …) …), where script is a symbol representing an OpenType script tag, langsys is a symbol representing an OpenType langsys tag (or nil, which stands for the default langsys), and each feature is a symbol representing an OpenType feature tag.

The following four functions return size information about fonts used by various faces, allowing various layout considerations in Lisp programs. These functions take face remapping into consideration, returning information about the remapped face, if the face in question was remapped. See section フェイスのリマップ.

Function: default-font-width: This function returns the average width in pixels of the font used by the current buffer’s default face.

Function: default-font-height: This function returns the height in pixels of the font used by the current buffer’s default face.

Function: window-font-width &optional window face: This function returns the average width in pixels for the font used by face in window. The specified window must be a live window. If nil or omitted, window defaults to the selected window, and face defaults to the default face in window.

Function: window-font-height &optional window face: This function returns the height in pixels for the font used by face in window. The specified window must be a live window. If nil or omitted, window defaults to the selected window, and face defaults to the default face in window.

39.13 フリンジ

グラフィカルなディスプレイでは、Emacsは各ウィンドウの隣にフリンジ(fringes)を描画します。これは切り詰め(truncation)、継続(continuation)、水平スクロールを示すビットマップを表示できる、側面の細い垂直ストリップです。

39.13.1 フリンジのサイズと位置		ウィンドウフリンジを置く場所を指定する。
39.13.2 フリンジのインジケーター		ウィンドウフリンジ内にインジケーターアイコンを表示する。
39.13.3 フリンジのカーソルFringe Cursors		右フリンジ内にカーソルを表示する。
39.13.4 フリンジのビットマップ		フリンジインジケーターにたいしてビットマップを指定する。
39.13.5 フリンジビットマップのカスタマイズ		フリンジ内で使用する独自ビットマップの指定。
39.13.6 オーバーレイ矢印		位置を示す矢印の表示。

39.13.1 フリンジのサイズと位置

以下のバッファーローカル変数は、そのバッファーを表示するウィンドウのフリンジの位置と幅を制御します。

Variable: fringes-outside-margins: フリンジは通常、ディスプレイマージンとウィンドウテキストの間に表示される。この値が非nilなら、フリンジはディスプレイマージンの外側に表示される。マージン内への表示を参照のこと。

Variable: left-fringe-width: この変数が非nilなら、それは左フリンジの幅をピクセル単位で指定する。値nilは、そのウィンドウのフレームの左フリンジ幅を使用することを意味する。

Variable: right-fringe-width: この変数が非nilなら、それは右フリンジの幅をピクセル単位で指定する。値nilは、そのウィンドウのフレームの右フリンジ幅を使用することを意味する。

これらの変数にたいして値を指定しないすべてのバッファーは、フレームパラメーターleft-fringeおよびright-fringeで指定された値を使用します(レイアウトのパラメーターを参照)。

上記の変数は、サブルーチンとしてset-window-fringesを呼び出す、関数set-window-buffer(バッファーとウィンドウを参照)を通じて実際に効果をもちます。これらの変数のいずれかを変更しても、影響を受ける各ウィンドウでset-window-bufferを呼び出さなければ、そのバッファーを表示する既存のウィンドウのフリンジ表示は更新されません。個別のウィンドウでのフリンジ表示を制御するために、set-window-fringesを使用することもできます。

Function: set-window-fringes window left &optional right outside-margins

この関数は、ウィンドウwindowのフリンジ幅をセットする。windowがnilなら、選択されたウィンドウが使用される。

引数leftは左フリンジ、同様にrightは右フリンジにたいして、ピクセル単位で幅を指定する。いずれかにたいする値nilは、デフォルトの幅を意味する。outside-marginsが非nilなら、フリンジをディスプレイマージンの外側に表示することを指定する。

The values specified here may be later overridden by invoking set-window-buffer (see section バッファーとウィンドウ) on window with its keep-margins argument nil or omitted.

Function: window-fringes &optional window: この関数は、ウィンドウwindowのフリンジに関する情報をリターンする。windowが省略またはnilなら、選択されたウィンドウが使用される。値は(left-width right-width outside-margins)の形式をもつ。

39.13.2 フリンジのインジケーター

フリンジインジケーター(Fringe indicators)は、行の切り詰めや継続、バッファー境界などを示す、ウィンドウフリンジ内に表示される小さいアイコンのことです。

User Option: indicate-empty-lines: これが非nilなら、Emacsはグラフィカルなディスプレイ上で、バッファー終端にある空行それぞれにたいして、フリンジ内に特別なグリフを表示する。フリンジを参照のこと。この変数はすべてのバッファーにおいて、自動的にバッファーローカルになる。

User Option: indicate-buffer-boundaries

このバッファーローカル変数は、ウィンドウフリンジ内でバッファー境界とウィンドウのスクロールを示す方法を制御する。

Emacsはバッファー境界(そのバッファーの最初の行と最後の行)がスクリーン上に表示された際、それを三角アイコン(angle icon)で示すことができる。加えて、スクリーンより上にテキストが存在する場合は上矢印(up-arrow)、スクリーンの下にテキストが存在する場合は下矢印(down-arrow)をフリンジ内に表示して、それを示すことができる。

基本的な値として3つの値がある:

nil: これらのフリンジアイコンを何も表示しない。
left: 左フリンジに三角アイコンと矢印を表示する。
right: 右フリンジに三角アイコンと矢印を表示する。
その他の非alist: 左フリンジに三角アイコンを表示して、矢印を表示しない。

値がそれ以外なら、どのフリンジインジケーターをどこに表示するかを指定する、alistであること。alistの各要素は、(indicator . position)のような形式をもつ。ここでindicatorはtop、bottom、up、down、またはt(指定されていないすべてのアイコンをカバーする)のいずれかであり、positionはleft、right、またはnilのいずれかである。

たとえば((top . left) (t . right))は左フリンジにtop angleビットマップを、右フリンジにbottom angleビットマップと両arrowビットマップを配置する。左フリンジにangleビットマップを表示してarrowビットマップを表示しないようにするには、((top . left) (bottom . left))を使用する。

Variable: fringe-indicator-alist

このバッファーローカル変数は、論理的ロジカルフリンジインジケーターから、ウィンドウフリンジ内に実際に表示されるビットマップへのマッピングを指定する。値は(indicator . bitmaps)のような要素をもつalistである。ここでindicatorは論理的インジケータータイプ、bitmapsはそのインジケーターに使用するフリンジビットマップを指定する。

indicatorはそれぞれ、以下のシンボルのいずれかであること:

truncation, continuation.: 行の切り詰めと継続に使用される。
up, down, top, bottom, top-bottom: indicate-buffer-boundariesが非nilの際に使用される。upおよびdownは、そのウィンドウ端より上または下にあるバッファー境界を示す。topおよびbottomはバッファーの最上端または最下端のテキスト行を示す。top-bottomはバッファー内にテキスト行1行だけが存在することを示す。
empty-line: indicate-empty-linesが非nilの際に、空行を示すために使用される。
overlay-arrow: オーバーレイ矢印に使用される(オーバーレイ矢印を参照)。

各bitmapsの値には、シンボルのリスト(left right [left1 right1])を指定できる。シンボルleftとrightは、特定のインジケーターにたいして左、および/または右フリンジに表示するビットマップを指定する。left1とright1は、インジケーターbottomとtop-bottomに固有であり、最後の改行をもたない最後のテキスト行を示すために使用される。かわりに、bitmapsに左フリンジと右フリンジの両方で使用される、単一のシンボルを指定することもできる。

標準のビットマップシンボルのリストと、自身で定義する方法については、フリンジのビットマップを参照のこと。加えて、nilは空ビットマップ(表示されないインジケーター)を表す。

fringe-indicator-alistがバッファーローカルな値をもち、論理的インジケーターにたいしてビットマップが定義されていない、またはビットマップがtならば、fringe-indicator-alistのデフォルト値から、対応する値が使用される。

39.13.3 フリンジのカーソルFringe Cursors

ある行がウィンドウと正確に同じ幅なとき、2行を使用するかわりにEmacsは右フリンジ内にカーソルを表示します。フリンジ内のカーソルを表すために使用されるビットマップの違いは、カレントバッファーのカーソルタイプに依存します。

User Option: overflow-newline-into-fringe: これが非nilなら、ウィンドウと正確に同じ幅の(最後の改行文字に継続されない)行は、継続されない。ポイントが行端に達した際は、かわりにカーソルは右フリンジに表示される。

Variable: fringe-cursor-alist

この変数は、論理的カーソルタイプから、右フリンジ内に実際に表示されるフリンジビットマップへのマッピングを指定する。値は、各要素が(cursor-type . bitmap)のような形式をもつようなalistである。ここでbitmapは使用するフリンジビットマップ、cursor-typeは表示するカーソルタイプである。

cursor-typeはそれぞれbox、hollow、bar、hbar、hollow-smallのいずれかであること。最初の4つはフレームパラメーターcursor-typeの場合と同じ意味をもつ(カーソルのパラメーターを参照)。hollow-smallタイプは、特定のディスプレイ行にたいして通常のhollow-rectangleが高すぎる際に、hollowのかわりに使用される。

bitmapはそれぞれ、その論理的カーソルタイプにたいして表示される、フリンジビットマップを指定するシンボルであること。詳細は、フリンジのビットマップを参照のこと。

fringe-cursor-alistがバッファーローカルな値をもち、カーソルタイプにたいして定義されたビットマップが存在しなければ、fringes-indicator-alistのデフォルト値の、対応する値が使用される。

39.13.4 フリンジのビットマップ

フリンジビットマップ(fringe bitmaps)は、行の切り詰めや継続、バッファー境界、オーバーレイ矢印等にたいする論理的フリンジインジケーターを表現する、実際のビットマップです。それぞれのビットマップはシンボルにより表されます。これらのシンボルは、フリンジインジケーターからビットマップへのマッピングを行う変数fringe-indicator-alist(フリンジのインジケーターを参照)、およびフリンジカーソルからビットマップへのマッピングを行う変数fringe-cursor-alist(フリンジのカーソルFringe Cursorsを参照)により参照されます。

Lispプログラムも、その行内に出現する文字の1つにdisplayプロパティを使用することにより、左フリンジまたは右フリンジ内に、ビットマップを直接表示することができます。そのような表示指定は、以下の形式をもちます

(fringe bitmap [face])

fringeは、left-fringeかright-fringeいずれかのシンボルです。bitmapは表示するビットマップを識別するシンボルです。オプションのfaceは、そのフォアグラウンドカラーをビットマップの表示に使用するフェイスの名前です。このフェイスは、自動的にfringeフェイスにマージされます。

以下はEmacsが定義する、標準的なフリンジビットマップと、(fringe-indicator-alistおよびfringe-cursor-alistを通じて)Emacs内で現在それらが使用される方法のリストです。

left-arrow, right-arrow: 切り詰められた行を示すために使用される。
left-curly-arrow, right-curly-arrow: 継続された行を示すために使用される。
right-triangle, left-triangle: 前者はオーバーレイ矢印により使用され、後者は使用されない。
up-arrow, down-arrow, top-left-angle top-right-angle
bottom-left-angle, bottom-right-angle
top-right-angle, top-left-angle
left-bracket, right-bracket, top-right-angle, top-left-angle: バッファー境界を示すために使用される。
filled-rectangle, hollow-rectangle
filled-square, hollow-square
vertical-bar, horizontal-bar: フリンジカーソルの異なるタイプにたいして使用される。
empty-line, exclamation-mark, question-mark, exclamation-mark: Emacsの中核機能では使用されない。

次のサブセクションでは、フリンジビットマップを独自に定義する方法を説明します。

Function: fringe-bitmaps-at-pos &optional pos window

この関数は、、ウィンドウwindow内の位置posを含むディスプレイ行の、フリンジビットマップをリターンする。リターン値は(left right ov)という形式をもつ。ここでleftは左フリンジ内のフリンジビットマップにたいするシンボル(ビットマップなしならnil)、rightは同様に右フリンジにたいして、ovが非nilなら左ふりんじにオーバーレイ矢印が存在することを意味する。

window内でposが可視でなければ、値はnilとなる。windowがnilなら、それは選択されたウィンドウを意味する。posがnilなら、それはwindow内のポイントの値を意味する。

39.13.5 フリンジビットマップのカスタマイズ

Function: define-fringe-bitmap bitmap bits &optional height width align

この関数は、シンボルbitmapを新たなフリンジビットマップとして定義、またはその名前の既存のビットマップを置き換える。

引数bitsは、使用するイメージを指定する。これは、各要素(整数)が対応するビットマップの1行を指定する、文字列または整数ベクターであること。整数の各ビットはそのビットマップの1ピクセルに対応し、低位ビットはそのビットマップの最右ピクセルに対応する。

高さは通常、bitsの長さである。しかし非nilのheightにより、異なる高さを指定できる。幅は通常は8だが、非nilのwidthにより、異なる幅を指定できる。widthは、1から16の整数でなければならない。

引数alignは、そのビットマップが使用される行範囲に相対的な、ビットマップの位置を指定する。デフォルトは、そのビットマップの中央である。指定できる値はtop、center、bottom。

align引数にはリスト(align periodic)も指定でき、alignは上述のように解釈される。periodicが非nilなら、それはbits内の行が指定される高さに達するのに十分な回数繰り返されるべきであることを指定する。

Function: destroy-fringe-bitmap bitmap: この関数は、bitmapにより識別されるフリンジビットマップを破棄する。bitmapが標準フリンジビットマップを識別する場合は、それを完全に消去するかわりに、実際はそのビットマップの標準定義をリストアする。

Function: set-fringe-bitmap-face bitmap &optional face

これはフリンジビットマップbitmapにたいするフェイスに、faceをセットする。faceがnilなら、fringeフェイスを選択する。ビットマップのフェイスは、それを描画するカラーを制御する。

faceはfringeにマージされるため、通常faceはフォアグラウンドカラーだけを指定すること。

39.13.6 オーバーレイ矢印

オーバーレイ矢印(overlay arrow)は、バッファー内の特定の行にたいして、ユーザーに注意を促すために有用です。たとえば、デバッガーでのインターフェースに使用されるモードでは、オーバーレイ矢印は実行されているコード行を示します。この機能はオーバーレイ(overlays)にたいして、何も行いません(オーバーレイを参照)。

Variable: overlay-arrow-string: この変数は、特定の行にたいして注意を喚起するために表示する文字列、または矢印機能が使用されていなければnilを保持する。グラフィカルなディスプレイでは、この文字列のコンテンツは無視され、かわりにフリンジ領域からディスプレイ領域左側にグリフが表示される。

Variable: overlay-arrow-position

この変数は、オーバーレイ矢印を表示する箇所を示すマーカーを保持する。これは行の先頭となるポイントであること。非グラフィカルなディスプレイでは、その行の先頭に矢印テキストが表示され、矢印テキストが表示されないときに表示されるべきテキストがオーバーレイされる。その矢印は通常は短く、行は普通はインデントで開始されるので、通常は上書きが問題となることはない。

オーバーレイ矢印の文字列は、そのバッファーのoverlay-arrow-positionの値が、そのバッファー内を指す場合は、与えられた任意のバッファーで表示される。したがって、overlay-arrow-positionのバッファーローカルなバインディングを作成することにより、複数のオーバーレイ矢印の表示が可能である。しかしこれを達成するためには、overlay-arrow-variable-listを使用するほうが、通常はより明快である。

before-stringプロパティをもつオーバーレイを作成することにより、同様のことを行うことができます。オーバーレイのプロパティを参照してください。

変数overlay-arrow-variable-listを通じて、複数のオーバーレイ矢印を定義できます。

Variable: overlay-arrow-variable-list: この変数の値は、それぞれがオーバーレイ矢印の位置を指定する、変数のリストである。変数overlay-arrow-positionはこのリスト上にあるため、通常の意味をもつ。

このリスト上の各変数は、対応するオーバーレイ矢印位置に表示するための、オーバーレイ矢印文字列を指定するoverlay-arrow-stringプロパティ(テキスト端末用)、およびフリンジビットマップを指定するoverlay-arrow-bitmapプロパティ(グラフィカル端末用)をもつことができます。これらのプロパティがセットされていなければ、デフォルトのフリンジインジケーターoverlay-arrow-stringとoverlay-arrowが使用されます。

39.14 スクロールバー

Normally the frame parameter vertical-scroll-bars controls whether the windows in the frame have vertical scroll bars, and whether they are on the left or right. The frame parameter scroll-bar-width specifies how wide they are (nil meaning the default).

The frame parameter horizontal-scroll-bars controls whether the windows in the frame have horizontal scroll bars. The frame parameter scroll-bar-height specifies how high they are (nil meaning the default). See section レイアウトのパラメーター.

Horizontal scroll bars are not available on all platforms. The function horizontal-scroll-bars-available-p which takes no argument returns non-nil if they are available on your system.

The following three functions take as argument a live frame which defaults to the selected one.

Function: frame-current-scroll-bars &optional frame: This function reports the scroll bar types for frame frame. The value is a cons cell (vertical-type . horizontal-type), where vertical-type is either left, right, or nil (which means no vertical scroll bar.) horizontal-type is either bottom or nil (which means no horizontal scroll bar).

Function: frame-scroll-bar-width &optional frame: This function returns the width of vertical scroll bars of frame in pixels.

Function: frame-scroll-bar-height &optional frame: This function returns the height of horizontal scroll bars of frame in pixels.

You can override the frame specific settings for individual windows by using the following function:

Function: set-window-scroll-bars window &optional width vertical-type height horizontal-type

This function sets the width and/or height and the types of scroll bars for window window. If window is nil, the selected window is used.

width specifies the width of the vertical scroll bar in pixels (nil means use the width specified for the frame). vertical-type specifies whether to have a vertical scroll bar and, if so, where. The possible values are left, right, t, which means to use the frame’s default, and nil for no vertical scroll bar.

height specifies the height of the horizontal scroll bar in pixels (nil means use the height specified for the frame). horizontal-type specifies whether to have a horizontal scroll bar. The possible values are bottom, t, which means to use the frame’s default, and nil for no horizontal scroll bar.

The values specified here may be later overridden by invoking set-window-buffer (see section バッファーとウィンドウ) on window with its keep-margins argument nil or omitted.

The following four functions take as argument a live window which defaults to the selected one.

Function: window-scroll-bars &optional window

This function returns a list of the form (width columns vertical-type height lines horizontal-type).

The value width is the value that was specified for the width of the vertical scroll bar (which may be nil); columns is the (possibly rounded) number of columns that the vertical scroll bar actually occupies.

The value height is the value that was specified for the height of the horizontal scroll bar (which may be nil); lines is the (possibly rounded) number of lines that the horizontally scroll bar actually occupies.

Function: window-current-scroll-bars &optional window: This function reports the scroll bar type for window window. The value is a cons cell (vertical-type . horizontal-type). Unlike window-scroll-bars, this reports the scroll bar type actually used, once frame defaults and scroll-bar-mode are taken into account.

Function: window-scroll-bar-width &optional window: This function returns the width in pixels of window’s vertical scrollbar.

Function: window-scroll-bar-height &optional window: This function returns the height in pixels of window’s horizontal scrollbar.

If you don’t specify these values for a window with set-window-scroll-bars, the buffer-local variables vertical-scroll-bar, horizontal-scroll-bar, scroll-bar-width and scroll-bar-height in the buffer being displayed control the window’s scroll bars. The function set-window-buffer examines these variables. If you change them in a buffer that is already visible in a window, you can make the window take note of the new values by calling set-window-buffer specifying the same buffer that is already displayed.

You can control the appearance of scroll bars for a particular buffer by setting the following variables which automatically become buffer-local when set.

Variable: vertical-scroll-bar: This variable specifies the location of the vertical scroll bar. The possible values are left, right, t, which means to use the frame’s default, and nil for no scroll bar.

Variable: horizontal-scroll-bar: This variable specifies the location of the horizontal scroll bar. The possible values are bottom, t, which means to use the frame’s default, and nil for no scroll bar.

Variable: scroll-bar-width: This variable specifies the width of the buffer’s vertical scroll bars, measured in pixels. A value of nil means to use the value specified by the frame.

Variable: scroll-bar-height: This variable specifies the height of the buffer’s horizontal scroll bar, measured in pixels. A value of nil means to use the value specified by the frame.

Finally you can toggle the display of scroll bars on all frames by customizing the variables scroll-bar-mode and horizontal-scroll-bar-mode.

User Option: scroll-bar-mode: This variable controls whether and where to put vertical scroll bars in all frames. The possible values are nil for no scroll bars, left to put scroll bars on the left and right to put scroll bars on the right.

User Option: horizontal-scroll-bar-mode: This variable controls whether to display horizontal scroll bars on all frames.

39.15 ウィンドウディバイダー

Window dividers are bars drawn between a frame’s windows. A right divider is drawn between a window and any adjacent windows on the right. Its width (thickness) is specified by the frame parameter right-divider-width. A bottom divider is drawn between a window and adjacent windows on the bottom or the echo area. Its width is specified by the frame parameter bottom-divider-width. In either case, specifying a width of zero means to not draw such dividers. See section レイアウトのパラメーター.

Technically, a right divider belongs to the window on its left, which means that its width contributes to the total width of that window. A bottom divider belongs to the window above it, which means that its width contributes to the total height of that window. See section ウィンドウのサイズ. When a window has both, a right and a bottom divider, the bottom divider prevails. This means that a bottom divider is drawn over the full total width of its window while the right divider ends above the bottom divider.

Dividers can be dragged with the mouse and are therefore useful for adjusting the sizes of adjacent windows with the mouse. They also serve to visually set apart adjacent windows when no scroll bars or mode lines are present. The following three faces allow the customization of the appearance of dividers:

window-divider: ディバイダーの幅が3ピクセル未満のときは、このフェイスのフォアグラウンドカラーで塗りつぶしで描画される。これより広いディバイダーでは、最初と最後のピクセルを除く、内部にたいしてのみこのフェイスが使用される。
window-divider-first-pixel: これは少なくとも幅が3ピクセルあるディバイダーの、最初のピクセルを描画するために使用される。塗りつぶし(solid)の外観を得るためには、window-dividerフェイスに使用されるのと同じ値をセットすること。
window-divider-last-pixel: これは少なくとも幅が3ピクセルあるディバイダーの、最後のピクセルを描画するために使用される。塗りつぶし(solid)の外観を得るためには、window-dividerフェイスに使用されるのと同じ値をセットすること。

以下の2つの関数により、特定のウィンドウのディバイダーのサイズを取得できます。

Function: window-right-divider-width &optional window: windowの右ディバイダーの幅(厚さ)を、ピクセル単位でリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。最右ウィンドウにたいするリターン値は、常に0である。

Function: window-bottom-divider-width &optional window: windowの下ディバイダーの幅(厚さ)を、ピクセル単位でリターンする。windowは生きたウィンドウでなければならず、デフォルトは選択されたウィンドウである。ミニバッファーウィンドウ、またはミニバッファーがないフレームの最下ウィンドウにたいするリターン値は、常に0である。

39.16 `display`プロパティ

テキストプロパティ(またはオーバーレイプロパティ)displayは、テキストへのイメージ挿入、およびテキスト表示のその他の事相を制御します。displayプロパティの値は、ディスプレイ仕様、または複数のディスプレイ仕様を含むリストかベクターであるべきです。同じdisplayプロパティ値内のディスプレイ仕様は、一般的にはそれらがカバーするテキストにたいして並行して適用されます。

複数のソース(オーバーレイ、および/またはテキストプロパティ)がdisplayプロパティにたいして値を指定しますが、1つの値だけが効果をもち、これはget-char-propertyのルールにしたがいます。テキストプロパティを調べるを参照してください。

Some of the display specifications allow inclusion of Lisp forms, which are evaluated at display time. This could be unsafe in certain situations, e.g., when the display specification was generated by some external program/agent. Wrapping a display specification in a list that begins with the special symbol disable-eval, as in ('disable-eval spec), will disable evaluation of any Lisp in spec, while still supporting all the other display property features.

このセクションの残りの部分では、複数の種類のディスプレイ仕様と、それらの意味を説明します。

39.16.1 テキストを置換するディスプレー仕様		テキストを置換するディスプレイspec。
39.16.2 スペースの指定		指定された幅に1つのスペースを表示する。
39.16.3 スペースにたいするピクセル指定		ピクセル単位でスペースの幅または高さを指定する。
39.16.4 その他のディスプレー仕様		イメージの表示。高さ、スペーシング、その他のテキストプロパティの調整。
39.16.5 マージン内への表示		メインテキスト側面へのテキストまたはイメージの表示。

39.16.1 テキストを置換するディスプレー仕様

ある種のディスプレイ仕様は、そのプロパティをもつテキストのかわりに表示する何かを指定します。これらは置換(replacing)ディスプレイ仕様と呼ばれます。Emacsはユーザーにたいして、この方法で置換されたバッファーテキストの中間への対話的なポイント移動を許していません。

ディスプレイ仕様のリストに1つ以上の置換ディスプレイ仕様が含まれる場合は、最初の置換ディスプレイ仕様が残りをオーバーライドします。置換ディスプレイ仕様は、他のほとんどのディスプレイ仕様は置換を許容しないので、それらとは無関係です。

For replacing display specifications, the text that has the property means all the consecutive characters that have the same Lisp object as their display property; these characters are replaced as a single unit. If two characters have different Lisp objects as their display properties (i.e., objects which are not eq), they are handled separately.

以下は、この要点を示すための例です。文字列が置換ディスプレイ仕様としての役割をもち、指定された文字列のプロパティをもつテキストを置換します(その他のディスプレー仕様を参照)。以下の関数を考えてみてください:

(defun foo ()
  (dotimes (i 5)
    (let ((string (concat "A"))
          (start (+ i i (point-min))))
      (put-text-property start (1+ start) 'display string)
      (put-text-property start (+ 2 start) 'display string))))

この関数は、バッファー内の最初の10文字それぞれにたいして、文字列"A"であるようなdisplayプロパティを与えますが、これらはすべて同じ文字列オブジェクトを取得しません。最初の2文字は同じ文字列オブジェクトなので、1つの‘A’に置換されます。2つの別々のput-text-property呼び出しでそのディスプレイプロパティが割り当てられたという事実は、無関係です。同様に次の2文字は2つ目の文字列(concatにより新たに作成された文字列オブジェクト)を取得するので、1つの‘A’で置換され、...となります。したがって、10文字は5つのAで表示されます。

39.16.2 スペースの指定

指定された幅、および/または高さのスペースを表示するためには、(space . props)という形式のディスプレイ仕様を使用します。このプロパティを、1つ以上の連続する文字にputすることができます。これらすべての文字のかわりに、指定された高さと幅のスペースが表示されます。以下は、スペースのウェイトを指定するために、props内で使用できるプロパティです:

:width width: widthが数字なら、それはスペースの幅が通常の文字幅のwidth倍であるべきかを指定する。widthはピクセル幅(pixel width)仕様でも可(スペースにたいするピクセル指定を参照)。
:relative-width factor: Specifies that the width of the stretch should be computed from the first character in the group of consecutive characters that have the same display property. The space width is the pixel width of that character, multiplied by factor. (On text-mode terminals, the “pixel width” of a character is usually 1, but it could be more for TABs and double-width CJK characters.)
:align-to hpos: スペースがhposに達するほど、十分に広くあるべきことを指定する。hposが数字なら、それは通常の文字幅の単位で量られる。hposはピクセル幅(pixel width)仕様でも可(スペースにたいするピクセル指定を参照)。

上記プロパティのいずれか1つのみを使用するべきです。以下のプロパティで、スペースの高さも指定できます:

:height height: スペースの高さを指定する。heightが数字なら、それはスペースの高さが通常の文字高さのheight倍であるべきことを指定する。heightはピクセル高さ仕様(pixel height)でも可(スペースにたいするピクセル指定を参照)。
:relative-height factor: このディスプレイ仕様をもつテキストの通常の高さにfactorを乗じることにより、スペースの高さを指定する。
:ascent ascent: ascentの値が非負の100以下の数字なら、スペースの高さのascentパーセントをスペースのアセント(ascent: 上方)、すなわちベースラインより上の部分とみなす。ピクセルアセント(pixel ascent)仕様により、アセントをピクセル単位で指定することも可(スペースにたいするピクセル指定を参照)。

:heightと:relative-heightを両方一緒に使用しないでください。

:widthと:align-toプロパティは非グラフィック端末でサポートされますが、このセクションのその他のスペースプロパティはサポートされません。

スペースプロパティは、双方向テキスト表示の並べ替えのために、パラグラフ区切りとして扱われます。詳細は、双方向テキストの表示を参照してください。

39.16.3 スペースにたいするピクセル指定

プロパティ:width、:align-to、:height、:ascentの値は再表示の間に評価される、特別な種類の式です。その評価の結果は、ピクセルの絶対数として使用されます。

以下の式がサポートされています:

  expr ::= num | (num) | unit | elem | pos | image | xwidget | form
  num  ::= integer | float | symbol
  unit ::= in | mm | cm | width | height

  elem ::= left-fringe | right-fringe | left-margin | right-margin
        |  scroll-bar | text
  pos  ::= left | center | right
  form ::= (num . expr) | (op expr ...)
  op   ::= + | -

The form num specifies a fraction of the default frame font height or width. The form (num) specifies an absolute number of pixels. If num is a symbol, symbol, its buffer-local variable binding is used; that binding can be either a number or a cons cell of the forms shown above (including yet another cons cell whose car is a symbol that has a buffer-local binding).

The in, mm, and cm units specify the number of pixels per inch, millimeter, and centimeter, respectively. The width and height units correspond to the default width and height of the current face. An image specification of the form (image . props) (see section イメージのディスクリプタ) corresponds to the width or height of the specified image. Similarly, an xwidget specification of the form (xwidget . props) stands for the width or height of the specified xwidget. See section Embedded Native Widgets.

The elements left-fringe, right-fringe, left-margin, right-margin, scroll-bar, and text specify the width of the corresponding area of the window. When the window displays line numbers (see section 表示されるテキストのサイズ), the width of the text area is decreased by the screen space taken by the line-number display.

The left, center, and right positions can be used with :align-to to specify a position relative to the left edge, center, or right edge of the text area. When the window displays line numbers, the left and the center positions are offset to account for the screen space taken by the line-number display.

(textを除く)上記ウィンドウ要素は、与えられたエリアの左端から相対的に位置を指定するために、:align-toとともに使用することもできます。 Any of the above window elements (except ) can also be used with to specify that the position is relative to the left edge of the given area. (最初に出現するこれらシンボルのいずれかにより)相対的位置にたいするベースオフセットが一度セットがされると、残りのシンボルは指定されたエリアの幅として解釈されます。たとえば左マージンの中央に位置揃えするには、以下のようにします

:align-to (+ left-margin (0.5 . left-margin))

If no specific base offset is set for alignment, it is always relative to the left edge of the text area. For example, ‘:align-to 0’ in a header-line aligns with the first text column in the text area. When the window displays line numbers, the text is considered to start where the space used for line-number display ends.

A value of the form (num . expr) stands for the product of the values of num and expr. For example, (2 . in) specifies a width of 2 inches, while (0.5 . image) specifies half the width (or height) of the specified image (which should be given by its image spec).

フォーム(+ expr ...)は、式の値を合計します。フォーム(- expr ...)は式の値を否定または減算します。

39.16.4 その他のディスプレー仕様

以下は、displayテキストプロパティ内で使用できる、その他のディスプレイ仕様です。

string

このプロパティをもつテキストのかわりに、stringを表示する。

再帰的なディスプレイ仕様はサポートされない。つまりstringのdisplayプロパティがあっても、それは使用されない。

(image . image-props)

この種のディスプレイ仕様は、イメージディスクリプタである(イメージを参照)。ディスプレイ仕様として使用時は、そのディスプレイ仕様をもつテキストのかわりに表示するイメージを意味する。

(slice x y width height)

この仕様はimageとともに、表示するイメージのスライス(slice: イメージの特定の領域)を指定する。要素yとxは、そのイメージ内での左上隅を指定し、widthとheightはそのスライスの幅と高さを指定する。整数はピクセル数、0.0から1.0までの浮動小数点数はイメージ全体の幅または高さの割合を意味する。A floating-point number in the range 0.0–1.0 stands for that fraction of the width or height of the entire image.

((margin nil) string)

この形式のディスプレイ仕様は、このディスプレイ仕様をもつテキストのかわりに、そのテキストと同じ位置に表示するstringを意味する。これは単にstringを使用するのと同じだが、マージン表示(マージン内への表示を参照)の特殊なケースとして行われる点が異なる。

(left-fringe bitmap [face])

(right-fringe bitmap [face])

テキスト行の任意の文字がこのディスプレイ仕様をもつ場合は、その文字のかわりにその行の左または右フリンジに表示するbitmapを指定する。オプションのfaceは、そのビットマップにたいして使用するカラーを指定する。詳細はフリンジのビットマップを参照のこと。

(space-width factor)

このディスプレイ仕様は、この仕様をもつテキスト内のすべてのスペース文字に効果を及ぼす。これらすべてのスペースは、通常の幅のfactor倍の幅で表示される。要素factorは整数か浮動小数点数であること。スペース以外の文字は影響を受けない。特に、これはタブ文字に影響を与えない。

(height height)

このディスプレイ仕様は、テキストを高く(taller)、または低く(shorter)する。heightには以下を指定できる:

(+ n): This means to use a font that is n steps larger. A step is defined by the set of available fonts—specifically, those that match what was otherwise specified for this text, in all attributes except height. Each size for which a suitable font is available counts as another step. n should be an integer.
(- n): これはnステップ小さいフォントの使用を意味する。
factor(数値): 数値factorは、デフォルトフォントのfactor倍高いフォントの使用を意味する。
function(シンボル): 高さを計算する関数。この関数はカレントの高さを引数として呼び出され、使用する新たな高さをリターンすること。
form(上記以外): heightの値が上記のいずれにもマッチしなければ、それはフォームである。Emacsはheightをカレントで指定されたフォントの高さにバインドして、新たな高さを取得するために、そのフォームを評価する。

(raise factor)

This kind of display specification raises or lowers the text it applies to, relative to the baseline of the line. It is mainly meant to support display of subscripts and superscripts.

The factor must be a number, which is interpreted as a multiple of the height of the affected text. If it is positive, that means to display the characters raised. If it is negative, that means to display them lower down.

Note that if the text also has a height display specification, which was specified before (i.e. to the left of) raise, the latter will affect the amount of raising or lowering in pixels, because that is based on the height of the text being raised. Therefore, if you want to display a sub- or superscript that is smaller than the normal text height, consider specifying raise before height.

任意のディスプレイ仕様にたいして、条件を作成できます。これを行うには、(when condition . spec)という形式の別リスト内にパッケージします。この場合、仕様specはconditionが非nil値に評価されたときだけ適用されます。この評価の間、objectは条件つきdisplayプロパティをもつ文字列、またはバッファーにバインドされます。positionとbuffer-positionはそれぞれobject内の位置、およびdisplayプロパティが見つかったバッファー位置にバインドされます。objectが文字列の際は、両者の位置は異なるかもしれません。

39.16.5 マージン内への表示

バッファーはその左側と右側に、ディスプレイマージン(display margins)と呼ばれる、ブランクエリアをもつことができます。それらのエリア内には、通常はテキストが出現することはありませんが、displayプロパティを使用して、ディスプレイマージン内に何かを配置することができます。現在のところ、マージン内のテキストやイメージをマウスセンシティブにする方法はありません。

マージン内に何かを表示するには、テキストのdisplayプロパティのマージン表示仕様(margin display specification)で、それを指定します。これは、配置したテキストが表示されないことを意味する、置換表示仕様です。マージン表示は表示されますが、そのテキストは表示されません。

マージン表示仕様とは((margin right-margin) spec)や((margin left-margin) spec)のようなものです。ここでspecは、マージン内に何を表示するかを告げる、別の表示仕様です。典型的にはこれは表示するテキスト文字列、またはイメージディスクリプタです。

特定のバッファーテキストに関連するマージンに何かを表示するためには、そのテキストにbefore-stringプロパティを付して、そのコンテンツとしてマージン表示仕様をputします。

Note that if the string to be displayed in the margin doesn’t specify a face, its face is determined using the same rules and priorities as it is for strings displayed in the text area (see section フェイスの表示). If this results in undesirable “leaking” of faces into the margin, make sure the string has an explicit face specified for it.

ディスプレイマージンが何かを表示可能になる前に、それらに非0の幅を与えなければなりません。これを行う通常の方法は、以下の変数をセットする方法です:

Variable: left-margin-width: この変数は左マージンの幅を、文字セル(別名は“列”)単位で指定する。これは、すべてのバッファーでバッファーローカルである。値nilは、左マージンエリアなしを意味する。

Variable: right-margin-width: この変数は右マージンの幅を、文字セル単位で指定する。これは、すべてのバッファーでバッファーローカルである。値nilは、右マージンエリアなしを意味する。

これらの変数をセットしても、そのウィンドウには即座には反映されません。これらの変数は、そのウィンドウ内に新たなバッファーを表示する際にチェックされます。したがって、set-window-bufferを呼び出すことにより、変更を反映することができます。

マージン幅を即座にセットすることもできます。

Function: set-window-margins window left &optional right

この関数は、ウィンドウwindowのマージン幅を、文字セル単位で指定する。引数leftは左マージン、rightは右マージン(デフォルトは0)を制御する。

The values specified here may be later overridden by invoking set-window-buffer (see section バッファーとウィンドウ) on window with its keep-margins argument nil or omitted.

Function: window-margins &optional window: この関数は、windowの左マージンと右マージンの幅を、(left . right)という形式のコンスセルでリターンする。2つのマージンエリアのいずれか一方が存在しなければ、その幅はnilとしてリターンされる。2つのマージンがどちらも存在しない場合、この関数は(nil)をリターンする。windowがnilなら、選択されたウィンドウが使用される。

39.17 イメージ

Emacsバッファー内にイメージを表示するためには、最初にイメージディスクリプタを作成して、それを表示されるテキストのdisplayプロパティ(displayプロパティを参照)内のディスプレイ指定子として使用しなければなりません。

Emacsはグラフィカルな端末で実行時は、通常はイメージの表示が可能です。テキスト端末、イメージサポートを欠く特定のグラフ^ィカル端末、またはイメージサポートなしでコンパイルされたEmacsでは、イメージは表示できません。原則イメージが表示可能か判断するためには、関数display-images-pを使用できます(ディスプレー機能のテストを参照)。

39.17.1 イメージのフォーマット		サポートされるイメージフォーマット。
39.17.2 イメージのディスクリプタ		`:display`内で使用されるイメージの指定方法。
39.17.3 XBMイメージ		XBMフォーマット用の特別な機能。
39.17.4 XPMイメージ		XPMフォーマット用の特別な機能。
39.17.5 ImageMagickイメージ		ImageMagickを通じて利用できる特別な機能。
39.17.6 SVG Images		Creating and manipulating SVG images.
39.17.7 その他のイメージタイプ		サポートされるその他さまざまなフォーマット。
39.17.8 イメージの定義		後で使用するためにイメージを定義する便利な方法。
39.17.9 イメージの表示		一度定義されたイメージを表示するための便利な方法。
39.17.10 マルチフレームのイメージ		1つ以上のフレームを含むイメージ。
39.17.11 イメージキャッシュ		イメージ表示の内部的メカニズム。

39.17.1 イメージのフォーマット

Emacsは、いくつかの異なるフォーマットのイメージを表示できます。これらのイメージフォーマットのいくつかは、特定のサポートライブラリーがインストールされている場合のみサポートされます。いくつかのプラットフォームでは、Emacsはオンデマンドでサポートライブラリーをロードできます。そのような場合には、それらの動的ライブラリーにたいする既知の名前セットを変更するために、変数dynamic-library-alistを使用できます。動的にロードされるライブラリーを参照してください。

Supported image formats (and the required support libraries) include PBM and XBM (which do not depend on support libraries and are always available), XPM (libXpm), GIF (libgif or libungif), JPEG (libjpeg), TIFF (libtiff), PNG (libpng), and SVG (librsvg).

Each of these image formats is associated with an image type symbol. The symbols for the above formats are, respectively, pbm, xbm, xpm, gif, jpeg, tiff, png, and svg.

さらにImageMagick(libMagickWand)のサポートつきでEmacsをビルドした場合には、EmacsはImageMagickが表示可能なイメージフォーマットを表示できます。ImageMagickイメージを参照してください。ImageMagickを通じて表示されるすべてのイメージは、タイプシンボルimagemagickをもちます。

Variable: image-types

この変数はカレント構成で潜在的にサポートされるイメージフォーマットにたいする、タイプシンボルのリストを含む。

“潜在的”とは、Emacsがそのイメージタイプを知っていることを意味しており、実際に使用可能である必要はない(たとえば動的ライブラリーが利用できないせいかもしれない)。どのイメージタイプが実際に利用できるか知るためには、image-type-available-pを使用すること。

Function: image-type-available-p type

この関数は、タイプtypeのイメージのロードおよび表示が可能なら非nilをリターンする。typeはイメージタイプシンボルであること。

サポートライブラリーが静的にリンクされたイメージタイプにたいして、この関数は常にtをリターンする。サポートライブラリーが動的にロードされるイメージタイプにたいしては、そのライブラリーがロード可能ならt、それ以外ならnilをリターンする。

39.17.2 イメージのディスクリプタ

イメージディスクリプタ(image descriptor)とは、イメージにたいする基礎的なデータと、それを表示する方法を指定するリストです。これは通常、オーバーレイプロパティまたはテキストプロパティdisplay(その他のディスプレー仕様を参照)の値を通じて使用されますが、バッファーにイメージを挿入する便利なヘルパー関数については、イメージの表示を参照してください。

イメージディスクリプタはそれぞれ(image . props)という形式をもちます。ここでpropsはキーワードシンボルと値のペアーからなるプロパティリストで、少なくともそのイメージタイプを指定するペアー:type typeを含みます。

以下は、すべてのイメージタイプにたいして意味のあるプロパティのリストです(以降のサブセクションで説明するように、特定のイメージタイプにたいしてのみ意味があるプロパティも存在する):

:type type

イメージタイプ。イメージのフォーマットを参照のこと。すべてのイメージディスクリプタは。このプロパティを含まなければならない。

:file file

これは、ファイルfileからイメージをロードすることを意味する。fileが絶対ファイル名でなければ、それはdata-directory内で展開される。

:data data

これは、rawイメージデータを指定する。すべてのイメージディスクリプタは、:dataか:fileのいずれかをもたなければならないが、両方もつことはできない。

ほとんどのイメージタイプにたいして、:dataプロパティの値はイメージデータを含む、文字列であること。いくつかのイメージタイプは、:dataをサポートしない。それ以外のイメージタイプにたいしては、:data単独では不十分であり、:dataとともに他のイメージプロパティを使用する必要がある。詳細は、以下のサブセクションを参照のこと。

:margin margin

これは、そのイメージ周囲に余分なマージンとして、何ピクセル追加するかを指定する。値marginは非負の数値、またはそのような数値のペアー(x . y)でなければならない。ペアーの場合、xは水平方向に追加するピクセル数、yは垂直方向に追加するピクセル数を指定する。:marginが指定されない場合のデフォルトは0。

:ascent ascent

これは、イメージのアセント(ベースラインの上の部分)に使用する、そのイメージの高さの分量を指定する。値ascentは、から100の数値、またはシンボルcenterでなければならない。

ascentが数値なら、アセントに使用するイメージの高さのパーセンテージであること。

ascentがcenterなら、そのイメージにたいしてテキストプロパティおよびオーバーレイプロパティにより指定される方法で、センターライン(そのイメージ位置にテキストを描画する際の垂直方向のセンターライン)の垂直方向中心にイメージが配置される。

このプロパティが省略された場合のデフォルトは500。

:relief relief

これは、イメージ注意にシャドー矩形を追加する。値reliefは、シャドーライン幅をピクセルで指定する。reliefが負ならボタンを押下した状態、それ以外はボタンを押下していない状態のイメージでシャドーを描画する。

:conversion algorithm

これは、イメージを表示する前に適用するべき、変換アルゴリズムを指定する。値algorithmは、どのアルゴリズムかを指定する。

laplace

emboss

Specifies the Laplace edge detection algorithm, which blurs out small differences in color while highlighting larger differences. People sometimes consider this useful for displaying the image for a disabled button.

(edge-detection :matrix matrix :color-adjust adjust)

一般的なエッジ検出アルゴリズムを指定する。matrixは数値からなる9要素のリスト、またはベクターでなければならない。変換されたイメージ内の位置x/yにあるピクセルは、その位置周辺にある元のピクセルから計算される。matrixは、x/yに近接する各ピクセルにたいして、そのピクセルが変換先ピクセルに影響するファクター(factor: 要因)を指定する。以下のように、要素0はx-1/y-1にあるピクセルのファクター、要素1はx/y-1にあるピクセルにたいするファクター、...を指定する。

  (x-1/y-1  x/y-1  x+1/y-1
   x-1/y    x/y    x+1/y
   x-1/y+1  x/y+1  x+1/y+1)

結果のピクセルは、周辺ピクセルのRGB値を合計したカラーを指定されたファクターで乗じ、その合計をファクター絶対値の合計で除した色強度から計算される。

ラプラスエッジ検出は、現在のところは以下のマトリクス

  (1  0  0
   0  0  0
   0  0 -1)

エンボスエッジ検出(Emboss edge-detection)は以下のマトリクスを使用する

  ( 2 -1  0
   -1  0  1
    0  1 -2)

disabled

Specifies transforming the image so that it looks disabled.

:mask mask

maskがheuristicか(heuristic bg)なら、フレームのバックグラウンドがイメージ背後に見えるよう、そのイメージのクリッピングマスクを構築する。bgが未指定またはtなら、イメージ4隅に最頻するカラーをそのイメージのバックグラウンドカラーとみなしてバックグラウンドカラーを決定する。それ以外ならbgは、そのイメージのバックグラウンドとみなすべきカラーを指定するリスト(red green blue)でなければならない。

maskがnilなら、イメージがマスクをもつ場合はマスクを削除する。マスクを含むフォーマットのイメージは、:mask nilを指定することにより削除される可能性がある。

:pointer shape

これはマウスポインターがそのイメージ上にある際の、ポインターシェイプを指定する。利用可能なポインターシェイプについては、ポインターの形状を参照のこと。

:map map

これは、そのイメージにホットスポット(hot spots)のイメージマップを関連付ける。

イメージマップは、各要素が(area id plist)という形式をもつalistである。areaはにはrectangle(矩形)、circle(円)、またはpolygon(ポリゴン、多角形)のいずれかを指定する。

rectangleは、矩形エリアの左上隅と右下隅のピクセル座標を指定するコンス(rect . ((x0 . y0) . (x1 . y1)))である。

circleは、円の中心と半径を指定するコンス(circle . ((x0 . y0) . r))である。rは整数または浮動小数点数。

polygonは、各ペアーが多角形の1つの頂点を記述するコンス(poly . [x0 y0 x1 y1 ...])である。

マウスポインターがホットスポット上にある際は、そのホットスポットのplistが参照される。これがhelp-echoプロパティを含むならそのホットスポットのツールチップを指定し、pointerプロパティを含む場合はマウスカーソルがホットスポット上にあるときのマウスカーソルのシェイプを指定する。利用可能なポインターシェイプについては、ポインターの形状を参照のこと。

マウスポインターがホットスポット上にあるときにマウスをクリックしたときのイベントは、ホットスポットのidとマウスイベントを組み合わせて構成される。たとえば、ホットスポットのidがarea4なら、[area4 mouse-1]となる。

Function: image-mask-p spec &optional frame: この関数は、イメージspecがマスクビットマップをもつなら、tをリターンする。frameはそのイメージが表示されるフレームである。frameがnilまたは省略された場合は、選択されたフレームが使用される(入力のフォーカスを参照)。

39.17.3 XBMイメージ

XBMフォーマットを使用するには、イメージタイプとしてxbmを指定します。このイメージフォーマットは外部ライブラリーを要求せず、このタイプのイメージは常にサポートされます。

xbmイメージタイプにたいして、追加のイメージプロパティがサポートされます:

:foreground foreground: 値foregroundはそのイメージのフォアグラウンドカラーを指定する文字列、またはデフォルトカラーを指定するnilであること。このカラーはXBM内の1の各ピクセルに使用される。デフォルトは、そのフレームのフォアグラウンドカラーである。
:background background: 値backgroundはそのイメージのバックグラウンドカラーを指定する文字列、またはデフォルトカラーを指定するnilであること。このカラーはXBM内の0の各ピクセルに使用される。デフォルトは、そのフレームのバックグラウンドカラーである。

外部ファイルのかわりに、Emacs内のデータを指定してXBMイメージを指定するには、以下の3つのプロパティを使用する:

:data data

値dataは、そのイメージのコンテンツを指定する。dataとして使用できる、3つのフォーマットが存在する:

それぞれがイメージの1ラインを指定するような、文字列ベクターまたはboolベクター。:heightと:widthを指定する。
文字列なら、XBMファイルが含むのと同じバイトシーケンスを含む。この場合は:heightと:widthを指定してはならない。これらを省略することが、そのデータがXBMファイルのフォーマットをもつことを示すからである。イメージの高さと幅は、ファイルのコンテンツにより指定される。
イメージのビット(もしかしたら終端の使用されない余分なビットを含む)を含む文字列、またはboolベクター。少なくともwidth * heightビットを含むこと。この場合は、その文字列がXBMファイル全体ではなく、単にビットだけを含むことを示すとともに、そのイメージのサイズを指定するために、:heightと:widthを指定しなければならない。

:width width

値widthは、ピクセル単位でイメージの幅を指定する。

:height height

値heightは、ピクセル単位でイメージの高さを指定する。

39.17.4 XPMイメージ

XPMフォーマットを使用するには、イメージタイプにxpmを指定します。xpmイメージタイプでは、追加のプロパティ:color-symbolsにも意味があります。

:color-symbols symbols: 値symbolsは、要素が(name . color)という形式をもつようなalistであること。各要素において、nameはイメージファイル内に出現するカラー名、colorはそのカラー名の実際の表示に使用するカラーを指定する。

39.17.5 ImageMagickイメージ

If your Emacs build has ImageMagick support, you can use the ImageMagick library to load many image formats (see File Conveniences in The GNU Emacs Manual). The image type symbol for images loaded via ImageMagick is imagemagick, regardless of the actual underlying image format.

To check for ImageMagick support, use the following:

(image-type-available-p 'imagemagick)

Function: imagemagick-types: この関数は、カレントのImageMagickインストールによりサポートされる、イメージファイル拡張子のリストをリターンする。リストの各要素は、.bmpイメージはBMPのように、イメージタイプにたいして内部的なImageMagick名を表すシンボルである。

User Option: imagemagick-enabled-types: この変数の値は、EmacsがImageMagickを使用してレンダリングを試みるかもしれない、ImageMagickイメージタイプのリストである。リストの各要素は、imagemagick-typesがリターンするリスト内のシンボルのいずれか、または等価な文字列である。もしくは値tはImageMagickにたいして利用できるすべてのイメージタイプを有効にする。この変数の値とは関係なく、imagemagick-types-inhibit(以下参照)が優先される。

User Option: imagemagick-types-inhibit: この変数の値は、imagemagick-enabled-typesの値とは無関係に、ImageMagickを使用して決してレンダリングされることのない、ImageMagickイメージタイプのリストである。値tは、ImageMagickを完全に無効にする。

Variable: image-format-suffixes: この変数は、イメージタイプをファイル名拡張子にマッピングするalistである。Emacsは、ImageMagickライブラリーにイメージのタイプに関するヒントを与えるために、この変数と:formatイメージプロパティ(以下参照)を組み合わせて使用する。各要素は(type extension)という形式をもち、typeはイメージのcontent-typeを指定するシンボル、extensionは関連付けられるファイル名拡張子を指定する文字列である。

ImageMagickによりロードされたイメージは、追加で以下のイメージディスクリプタプロパティをサポートします:

:background background

backgroundが非nilなら、カラーを指定する文字列であること。これはイメージが透明度をサポートする場合に、そのイメージのバックグラウンドカラーとして使用される。値がnilの場合のデフォルトは、そのフレームのバックグラウンドカラー。

:width width, :height height

キーワード:widthと:heightは、イメージのスケーリングに使用される。いずれか一方のみが指定された場合には、アスペクト比を保つために、もう一方は算出される。両方が指定された場合には、アスペクト比は保たれないかもしれない。

:max-width max-width, :max-height max-height

キーワード:max-widthと:max-heightは、イメージのサイズがこれらの値を超過した場合のスケーリングに使用される。:widthがセットされた場合にはmax-widthより優先され、:heightがセットされた場合にはmax-heightより優先されるだろうが、それ以外ではこれらのキーワードを望むように混交できる。:max-widthと:max-heightは常に、アスペクト比を保つであろう。

If both :width and :max-height has been set (but :height has not been set), then :max-height will have precedence. The same is the case for the opposite combination: The “max” keyword has precedence. That is, if you have a 200x100 image and specify that :width should be 400 and :max-height should be 150, you’ll end up with an image that is 300x150: Preserving the aspect ratio and not exceeding the “max” setting. This combination of parameters is a useful way of saying “display this image as large as possible, but no larger than the available display area”.

:scale scale

This should be a number, where values higher than 1 means to increase the size, and lower means to decrease the size. For instance, a value of 0.25 will make the image a quarter size of what it originally was. If the scaling makes the image larger than specified by :max-width or :max-height, the resulting size will not exceed those two values. If both :scale and :height/:width are specified, the height/width will be adjusted by the specified scaling factor.

:format type

値typeは、image-format-suffixesで見られるような、イメージのタイプを指定するシンボルであること。これはイメージが関連付けられたファイル名をもたない際に、そのイメージタイプを検出する助けとなるヒントをImageMagickに提供する。

:rotation angle

回転角度を度数で指定する。

:index frame

マルチフレームのイメージを参照のこと。

39.17.6 SVG Images

SVG (Scalable Vector Graphics) is an XML format for specifying images. If your Emacs build has SVG support, you can create and manipulate these images with the following functions.

Function: svg-create width height &rest args

Create a new, empty SVG image with the specified dimensions. args is an argument plist with you can specify following:

:stroke-width: The default width (in pixels) of any lines created.
:stroke: The default stroke color on any lines created.

This function returns an SVG structure, and all the following functions work on that structure.

Function: svg-gradient svg id type stops

Create a gradient in svg with identifier id. type specifies the gradient type, and can be either linear or radial. stops is a list of percentage/color pairs.

The following will create a linear gradient that goes from red at the start, to green 25% of the way, to blue at the end:

(svg-gradient svg "gradient1" 'linear
              '((0 . "red") (25 . "green") (100 . "blue")))

The gradient created (and inserted into the SVG object) can later be used by all functions that create shapes.

All the following functions take an optional list of keyword parameters that alter the various attributes from their default values. Valid attributes include:

:stroke-width: The width (in pixels) of lines drawn, and outlines around solid shapes.
:stroke-color: The color of lines drawn, and outlines around solid shapes.
:fill-color: The color used for solid shapes.
:id: The identified of the shape.
:gradient: If given, this should be the identifier of a previously defined gradient object.

Function: svg-rectangle svg x y width height &rest args

Add a rectangle to svg where the upper left corner is at position x/y and is of size width/height.

(svg-rectangle svg 100 100 500 500 :gradient "gradient1")

Function: svg-circle svg x y radius &rest args: Add a circle to svg where the center is at x/y and the radius is radius.

Function: svg-ellipse svg x y x-radius y-radius &rest args: Add a circle to svg where the center is at x/y and the horizontal radius is x-radius and the vertical radius is y-radius.

Function: svg-line svg x1 y1 x2 y2 &rest args: Add a line to svg that starts at x1/y1 and extends to x2/y2.

Function: svg-polyline svg points &rest args

Add a multiple segment line to svg that goes through points, which is a list of X/Y position pairs.

(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100))
              :stroke-color "green")

Function: svg-polygon svg points &rest args

Add a polygon to svg where points is a list of X/Y pairs that describe the outer circumference of the polygon.

(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90))
             :stroke-color "blue" :fill-color "red"")

Function: svg-text svg text &rest args

Add a text to svg.

(svg-text
 svg "This is a text"
 :font-size "40"
 :font-weight "bold"
 :stroke "black"
 :fill "white"
 :font-family "impact"
 :letter-spacing "4pt"
 :x 300
 :y 400
 :stroke-width 1)

Function: svg-embed svg image image-type datap &rest args

Add an embedded (raster) image to svg. If datap is nil, IMAGE should be a file name; if not, it should be a binary string containing the image data. image-type should be a MIME image type, for instance ‘"image/jpeg"’.

(svg-embed svg "~/rms.jpg" "image/jpeg" nil
           :width "100px" :height "100px"
           :x "50px" :y "75px")

Function: svg-remove svg id: Remove the element with identifier id from the svg.

Finally, the svg-image takes an SVG object as its parameter and returns an image object suitable for use in functions like insert-image. Here’s a complete example that creates and inserts an image with a circle:

(let ((svg (svg-create 400 400 :stroke-width 10)))
  (svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue")))
  (svg-circle svg 200 200 100 :gradient "gradient1"
                  :stroke-color "green")
  (insert-image (svg-image svg)))

39.17.7 その他のイメージタイプ

PBMイメージには、イメージタイプpbmを指定します。カラー、グレースケール、およびモノクロのイメージがサポートされます。モノクロのPBMイメージにたいしては、2つの追加イメージプロパティがサポートされます。

:foreground foreground: 値foregroundは、そのイメージのフォアグラウンドカラーを指定する文字列、またはデフォルトカラーならnilであること。このカラーは、そのPBM内の1であるようなピクセルすべてに使用される。デフォルトは、フレームのフォアグラウンドカラー。
:background background: 値backgroundは、そのイメージのバックグラウンドカラーを指定する文字列、またはデフォルトカラーならnilであること。このカラーは、そのPBM内の0であるようなピクセルすべてに使用される。デフォルトは、フレームのバックグラウンドカラー。

Emacsがサポート可能な、残りのイメージタイプは以下のとおり:

GIF: イメージタイプgif。:indexプロパティをサポートする。マルチフレームのイメージを参照のこと。
JPEG: イメージタイプjpeg。
PNG: イメージタイプpng。
TIFF: イメージタイプtiff。:indexプロパティをサポートする。マルチフレームのイメージを参照のこと。

39.17.8 イメージの定義

関数create-image、defimage、find-imageはイメージディスクリプタを作成するための便利な手段を提供します。

Function: create-image file-or-data &optional type data-p &rest props

この関数は、file-or-data内のデータを使用するイメージディスクリプタを作成してリターンする。file-or-dataはファイル名、またはイメージデータを含む文字列を指定できる。前者の場合data-pはnil、後者なら非nilであること。

オプション引数typeは、イメージタイプを指定するシンボルである。typeが省略またはnilなら、create-imageはファイル先頭の数バイト、またはファイル名からイメージタイプの判断を試みる。

残りの引数propsは追加のイメージプロパティを指定する。たとえば、

(create-image "foo.xpm" 'xpm nil :heuristic-mask t)

このタイプのイメージがサポートされていなければ、この関数はnil、それ以外ならイメージディスクリプタをリターンする。

Macro: defimage symbol specs &optional doc

このマクロは、イメージマクロとしてsymbolを定義する。引数specsは、そのイメージの表示方法を指定するリストである。3つ目の引数docは、オプションのドキュメント文字列である。

specs内の各要素はプロパティリストの形式をもち、それぞれが少なくとも:typeプロパティと、:fileか:dataいずれかのプロパティをもつべきである。:typeの値はイメージタイプを指定するシンボル、:fileの値はイメージをロードするファイル、:dataの値は実際のイメージデータを含む文字列であること。以下は例である:

(defimage test-image
  ((:type xpm :file "~/test1.xpm")
   (:type xbm :file "~/test1.xbm")))

defimageはそれが使用可能か、つまりそのタイプがサポートされているかとファイルが存在するかを確認するために、各要素を1つずつテストする。最初に使用可能な引数が、symbol内に格納するイメージディスクリプタを作成するために使用される。

機能する候補がなければ、symbolはnilとして定義される。

Function: image-property image property: Return the value of property in image. Properties can be set by using setf. Setting a property to nil will remove the property from the image.

Function: find-image specs

この関数は、イメージ仕様specsのリストの1つを満足するイメージを探す、便利な手段を提供する。

specs内の各仕様は、イメージタイプに応じた内容のプロパティリストである。すべての仕様は少なくとも:type type、および:file fileか:data dataいずれかのプロパティを含まなければならない。ここでtypeはxbmのようにイメージタイプを指定するシンボル、fileはイメージをロードするファイル、dataは実際のイメージデータを含む文字列である。このリスト内でtypeがサポートされていて、かつfileが存在する最初の仕様は、リターンされるイメージ仕様の構築に使用される。満足する仕様がなければ、nilがリターンされる。

イメージは、image-load-path内で検索される。

User Option: image-load-path

This variable’s value is a list of locations in which to search for image files. If an element is a string or a variable symbol whose value is a string, the string is taken to be the name of a directory to search. If an element is a variable symbol whose value is a list, that is taken to be a list of directories to search.

The default is to search in the images subdirectory of the directory specified by data-directory, then the directory specified by data-directory, and finally in the directories in load-path. Subdirectories are not automatically included in the search, so if you put an image file in a subdirectory, you have to supply the subdirectory explicitly. For example, to find the image images/foo/bar.xpm within data-directory, you should specify the image as follows:

(defimage foo-image '((:type xpm :file "foo/bar.xpm")))

Function: image-load-path-for-library library image &optional path no-error

この関数は、Lispパッケージlibraryにより使用されるイメージにたいして、適切な検索パスをリターンする。

この関数はまずimage-load-path(data-directory/imagesを除外)を使用し、次にload-pathの後にlibraryにとって適切なパス(ライブラリーファイル自身にたいする相対パス../../etc/imagesと../etc/imagesを含む)を補い、最後にdata-directory/imagesからimageを検索する。

その後にこの関数は、先頭にimageが見つかったディレクトリー、その後にload-pathの値が続く、ディレクトリーのリストをリターンする。pathが与えられた場合は、それをload-pathのかわりに使用する。

no-errorが非nilで、かつ適切なパスが見つからない場合に、エラーをシグナルしない。かわりに前記のディレクトリーリストをリターンするが、イメージのディレクトリーの箇所にnilが出現する点が異なる。

以下はimage-load-path-for-libraryの使用例である:

(defvar image-load-path) ; shush compiler
(let* ((load-path (image-load-path-for-library
                    "mh-e" "mh-logo.xpm"))
       (image-load-path (cons (car load-path)
                              image-load-path)))
  (mh-tool-bar-folder-buttons-init))

Images are automatically scaled when created based on the image-scaling-factor variable. The value is either a floating point number (where numbers higher than 1 means to increase the size and lower means to shrink the size), or the symbol auto, which will compute a scaling factor based on the font pixel size.

39.17.9 イメージの表示

自分でdisplayプロパティをセットアップすることでイメージディスクリプタを使用できますが、このセクションの関数を使用するほうがより簡単です。

Function: insert-image image &optional string area slice

この関数は、カレントバッファーのポイント位置にimageを挿入する。imageは、イメージディスクリプタであること。これはcreate-imageによりリターンされた値、またはdefimageで定義されたシンボルの値かもしれない。引数stringは、イメージを保持するためにバッファー内に配すテキストを指定する。これが省略またはnilなら、insert-imageはデフォルトで" "を使用する。

引数areaは、マージン内にイメージを置くかどうかを指定する。これがleft-marginなら左マージンにイメージが表示され、right-marginなら右マージンを指定する。areaがnilまたは省略された場合、イメージはバッファーのテキスト内のポイント位置に表示される。

引数sliceは、挿入するイメージのスライスを指定する。sliceがnilまたは省略された場合は、そのイメージ全体が挿入される。それ以外では、sliceがリスト(x y width height)ならxとyは位置、widthとheightは挿入するイメージの領域を指定する。整数値はピクセル単位。0.0から1.0までの浮動小数点数は、イメージ全体の幅または高さにたいする割合を指定する。

内部的には、この関数はバッファー内にstringを挿入して、imageを指定するdisplayプロパティにそれを渡す。displayプロパティを参照のこと。

Function: insert-sliced-image image &optional string area rows cols

この関数はinsert-imageと同様、カレントバッファー内にimageを挿入するが、イメージをrows✕colsの同一サイズのスライスに分割する。

Emacs displays each slice as a separate image, and allows more intuitive scrolling up/down, instead of jumping up/down the entire image when paging through a buffer that displays (large) images.

Function: put-image image pos &optional string area

この関数は、カレントバッファー内のposの前に、イメージimageを配置する。引数posは整数、またはマーカーであること。これは、イメージが表示されるべきバッファー位置を指定する。引数stringは、代替として表示されるべきデフォルトのイメージを保持するテキストであること。

引数imageはイメージディスクリプタでなければならず、それはcreate-imageがリターンされたか、あるいはdefimageにより格納されたイメージディスクリプタかもしれない。

内部的には、この関数はオーバーレイを作成して、値がそのイメージであるようなdisplayプロパティをもつテキストを含む、before-stringプロパティをそのオーバーレイに与えている(なんと!)。

Function: remove-images start end &optional buffer

この関数は、bufferの位置startとendの間のイメージを削除する。bufferが省略またはnilなら、カレントバッファーからイメージを削除する。

これはput-imageが行う方法でbufferに配置されたイメージだけを削除し、insert-imageや他の方法で挿入されたイメージは削除しない。

Function: image-size spec &optional pixels frame: This function returns the size of an image as a pair (width . height). spec is an image specification. pixels non-nil means return sizes measured in pixels, otherwise return sizes measured in the default character size of frame (see section Frame Font). frame is the frame on which the image will be displayed. frame null or omitted means use the selected frame (see section 入力のフォーカス).

Variable: max-image-size

この変数は、Emacsがロードするイメージの最大サイズを定義するために使用される。Emacsはこの制限より大きいイメージのロード(と表示)を拒絶するだろう。

値が整数なら、それはピクセル単位で量ったイメージの最大の高さと幅を、直接指定する。浮動小数点数なら、そのフレームの高さおよび幅にたいする比率として、イメージの最大の高さと幅を指定する。値が数値でなければ、イメージサイズにたいする明示的な制限は存在しない。

この変数の目的は、意図せずEmacsに不当に大きなイメージがロードされるとを防ぐことである。これは、イメージの初回ロード時だけ効果がある。イメージが一度イメージキャッシュに置かれると、その後max-image-sizeの値が変更されても、そのイメージは常に表示可能である(イメージキャッシュを参照)。

Images inserted with the insertion functions above also get a local keymap installed in the text properties (or overlays) that span the displayed image. This keymap defines the following commands:

+: Increase the image size (image-increase-size). A prefix value of ‘4’ means to increase the size by 40%. The default is 20%.
-: Decrease the image size (image-increase-size). A prefix value of ‘4’ means to decrease the size by 40%. The default is 20%.
r: Rotate the image by 90 degrees (image-rotate).
o: Save the image to a file (image-save).

39.17.10 マルチフレームのイメージ

複数のイメージを含むことができるイメージファイルがいくつかあります。わたしたちはこのような場合、イメージ内に複数の“フレーム”があると表現しています。現在のところ、EmacsはGIF、TIFF、およびDJVMのような特定のImageMagickフォーマットにたいして、複数フレームをサポートします。

The frames can be used either to represent multiple pages (this is usually the case with multi-frame TIFF files, for example), or to create animation (usually the case with multi-frame GIF files).

マルチフレームイメージは、表示されるフレームを指定する整数値(0から数える)が値であるような、プロパティ:indexをもっています。

Function: image-multi-frame-p image: この関数は、imageが2つ以上のフレームを含む場合は、非nilをリターンする。実際のリターン値はコンス(nimages . delay)で、nimagesはフレーム数、delayはフレーム間の遅延秒数、イメージが遅延を指定しない場合はnilである。通常、アニメーションを意図されたイメージはフレームの遅延を指定し、複数ページとして扱われることを意図したイメージは指定しない。

Function: image-current-frame image: この関数はimageにたいして、0から数えたカレントフレーム番号のインデックスをリターンする。

Function: image-show-frame image n &optional nocheck: この関数は、imageをフレーム番号nとスイッチする。nocheckがnilなら、有効範囲外のフレーム番号を範囲終端に置き換える。imageが指定された番号のフレームを含まなければ、イメージは中貫きの四角(hollow box)で表示される。

Function: image-animate image &optional index limit: この関数は、imageをアニメーション表示する。オプションの整数indexは、開始するフレームを指定する(デフォルトは0)。オプション引数limitは、アニメーションの長さを制御する。これが省略またはnilなら、アニメーション回数は1回、tなら永久にループ表示する。数値なら、その秒数後にアニメーションは停止する。

アニメーションはタイマーにより処理されます。Emacsは最小のフレーム遅延を0.01秒(image-minimum-frame-delay)とすることに注意してください。そのイメージ自身が遅延を指定しなければ、Emacsはimage-default-frame-delayを使用します。

Function: image-animate-timer image: この関数は、もし存在すればimageのアニメーションに責任をもつタイマーをリターンする。

39.17.11 イメージキャッシュ

Emacsはイメージをより効果的に再表示できるように、イメージをキャッシュします。Emacsがイメージを表示する際、既存のイメージ仕様が望む仕様とequalなイメージキャッシュを検索します。マッチが見つかったら、そのイメージはキャッシュから表示され、それ以外ではイメージは通常のようにロードされます。

Function: image-flush spec &optional frame

この関数は、フレームframeのイメージキャッシュから、仕様specのイメージを削除する。イメージ仕様の比較には、equalを使用する。frameがnilの場合のデフォルトは選択されたフレーム。frameがtなら、そのイメージはすべての既存フレームでフラッシュされる。

Emacsのカレント実装では、各グラフィカル端末はイメージキャッシュを処理して、それはその端末上のすべてのフレームにより共有される(複数の端末を参照)。つまりあるフレームでイメージをリフレッシュすると、同一端末上の他のすべてのフレームでもリフレッシュされる。

image-flushの1つの用途は、Emacsにイメージファイルの変更を伝えることです。イメージ仕様が:fileプロパティを含む場合、そのイメージの初回表示時にそのファイルコンテンツにもとづいて、イメージがキャッシュされます。たとえその後にファイルが変更されても、Emacsはそのイメージの古いバージョンを表示し続けます。image-flushを呼び出すことによりそのイメージはキャッシュからフラッシュされ、そのイメージの表示が次回必要になった際に、Emacsにファイルの再読み込みを強制します。

image-flushの他の用途は、メモリー節約です。Lispプログラムでimage-cache-eviction-delay(以下参照)より遥かに短い期間に多数の一時イメージを作成する場合には、Emacsが自動的に行うことを待たずに、自身で使用されていないイメージのフラッシュを選択できます。

Function: clear-image-cache &optional filter: この関数は、イメージキャッシュ内に格納されたすべてのイメージを削除して、イメージキャッシュをクリアーする。filterが省略またはnilなら、選択されたフレームにたいしてキャッシュをクリアーする。filterがフレームなら、そのフレームにたいしてキャッシュをクリアーする。filterがtなら、すべてのイメージキャッシュをクリアーする。それ以外なら、filterはファイル名として解釈され、すべてのイメージキャッシュからそのファイル名に関連付けられたすべてのイメージを削除する。

イメージキャッシュ内のイメージが指定された期間内に表示されなければ、Emacsはそれをキャッシュから削除して、割り当てられたメモリーを解放します。

Variable: image-cache-eviction-delay

この変数は、表示されることなくイメージがキャッシュ内に残留できる秒数を指定する。あるイメージがこの秒数の間に表示されなければ、Emacsはそれをイメージキャッシュから削除する。

ある状況下では、もしキャッシュ内のイメージ数が大きくなり過ぎた場合には、実際の立ち退き遅延(eviction delay)はこれより短くなり得る。

値がnilなら、明示的にキャッシュをクリアーした場合を除き、Emacsはキャッシュからイメージを削除しない。このモードはデバッグ時に有用かもしれない。

39.18 Embedded Native Widgets

Emacs is able to display native widgets, such as GTK+ WebKit widgets, in Emacs buffers when it was built with the necessary support libraries and is running on a graphical terminal. To test whether Emacs supports display of embedded widgets, check that the xwidget-internal feature is available (see section 名前つき機能).

To display an embedded widget in a buffer, you must first create an xwidget object, and then use that object as the display specifier in a display text or overlay property (see section displayプロパティ).

Function: make-xwidget type title width height arguments &optional buffer

This creates and returns an xwidget object. If buffer is omitted or nil, it defaults to the current buffer. If buffer names a buffer that doesn’t exist, it will be created. The type identifies the type of the xwidget component, it can be one of the following:

webkit: The WebKit component.

The width and height arguments specify the widget size in pixels, and title, a string, specifies its title.

Function: xwidgetp object: This function returns t if object is an xwidget, nil otherwise.

Function: xwidget-plist xwidget: This function returns the property list of xwidget.

Function: set-xwidget-plist xwidget plist: This function replaces the property list of xwidget with a new property list given by plist.

Function: xwidget-buffer xwidget: This function returns the buffer of xwidget.

Function: get-buffer-xwidgets buffer: This function returns a list of xwidget objects associated with the buffer, which can be specified as a buffer object or a name of an existing buffer, a string. The value is nil if buffer contains no xwidgets.

Function: xwidget-webkit-goto-uri xwidget uri: This function browses the specified uri in the given xwidget. The uri is a string that specifies the name of a file or a URL.

Function: xwidget-webkit-execute-script xwidget script: This function causes the browser widget specified by xwidget to execute the specified JavaScript script.

Function: xwidget-webkit-execute-script-rv xwidget script &optional default: This function executes the specified script like xwidget-webkit-execute-script does, but it also returns the script’s return value as a string. If script doesn’t return a value, this function returns default, or nil if default was omitted.

Function: xwidget-webkit-get-title xwidget: This function returns the title of xwidget as a string.

Function: xwidget-resize xwidget width height: This function resizes the specified xwidget to the size widthxheight pixels.

Function: xwidget-size-request xwidget: This function returns the desired size of xwidget as a list of the form (width height). The dimensions are in pixels.

Function: xwidget-info xwidget: This function returns the attributes of xwidget as a vector of the form [type title width height]. The attributes are usually determined by make-xwidget when the xwidget is created.

Function: set-xwidget-query-on-exit-flag xwidget flag: This function allows you to arrange that Emacs will ask the user for confirmation before exiting or before killing a buffer that has xwidget associated with it. If flag is non-nil, Emacs will query the user, otherwise it will not.

Function: xwidget-query-on-exit-flag xwidget: This function returns the current setting of xwidgets query-on-exit flag, either t or nil.

39.19 ボタン

Buttonパッケージは、マウスまたはキーボードコマンドによりアクティブ化することができる、ボタン(buttons)の挿入と操作に関する関数を定義します。これらのボタンは典型的には、種々のハイパーリンクに使用されます。

本質的にボタンとは、バッファー内のテキスト範囲にアタッチされた、テキストプロパティまたはオーバーレイプロパティのセットです。これらのプロパティは、ボタンプロパティ(button properties)と呼ばれます。これらのプロパティのうちの1つはアクションプロパティ(action property)で、これはユーザーがキーボードかマウスを使用してボタンを呼び出した際に呼び出される関数を指定します。アクション関数はボタンを調べて、必要に応じて他のプロパティを使用できます。

いくつかの点において、ButtonパッケージとWidgetパッケージは機能的に重複しています。Introduction in The Emacs Widget Libraryを参照してください。Buttonパッケージの利点は、より高速で小さく、プログラムにたいしてよりシンプルであることです。ユーザーの観点からは、2つのパッケージが提供するインターフェイスは非常に類似しています。

39.19.1 ボタンのプロパティ		特別な意味をもつボタンプロパティ。
39.19.2 ボタンのタイプ		ボタンのクラスにたいして一般的なプロパティを定義する。
39.19.3 ボタンの作成		Emacsバッファーへのボタンの追加。
39.19.4 ボタンの操作		ボタンプロパティの取得とセット。
39.19.5 ボタンのためのバッファーコマンド		ボタンにたいするバッファー規模のコマンドとバインディング。

39.19.1 ボタンのプロパティ

ボタンはその外観と振る舞いを定義するプロパティの連想リスト(associated list)をもち、アプリケーションの特別な目的のために、他の任意のプロパティを使用できます。以下のプロパティは、Buttonパッケージにたいして特別な意味をもちます:

action: ユーザーがボタンを呼び出した際に呼び出す関数で、単一の引数buttonを渡して呼び出される。デフォルトではこれは、何も行わないignoreである。
mouse-action: これはactionと似ているが、もし与えられた際には、(RET押下のかわりに)マウスクリックによりボタンが呼び出された場合は、actionのかわりに使用される。与えられない場合、マウスクリックはかわりにactionを使用する。
face: これは、このタイプのボタンが表示される方法を制御するEmacsフェイスである。デフォルトではbuttonフェイス。
mouse-face: これはボタン上にマウスがある際の外観を制御する、追加のフェイスである(通常のbuttonフェイスとマージされる)。デフォルトでは、これはEmacsの通常のhighlightフェイスである。
keymap: そのボタンリージョン(button region)でアクティブなバインディングを定義する、ボタンのキーマップである。デフォルトでは、変数button-mapに格納された、通常のボタンリージョンキーマップで、これはボタン呼び出しにたいしてRETとmouse-2を定義している。
type: ボタンのタイプ。ボタンのタイプを参照のこと。
help-echo: Emacsのツールチップヘルプシステムにより表示あれる文字列。デフォルトでは"mouse-2, RET: Push this button"。
follow-link: The follow-link property, defining how a mouse-1 click behaves on this button, See section クリック可能なテキストの定義.
button: すべてのボタンは非nilのbuttonプロパティをもち、これはボタンを含むテキストリージョンを探すのに有用かもしれない()標準的なボタン関数はこれを行う。

ボタン内のテキストリージョンにたいして定義された他のプロパティも存在しますが、それらは典型的な用途にたいしては一般的に関係ないでしょう。

39.19.2 ボタンのタイプ

すべてのボタンは、そのボタンのプロパティにたいするデフォルト値を定義する、ボタンタイプ(button type)をもっています。ボタンタイプは、より汎用的なタイプから特化したタイプへと継承される階層構造で構成されており、特定のタスクにたいしては、特殊用途のボタンを簡単に定義できます。

Function: define-button-type name &rest properties

Define a button type called name (a symbol). The remaining arguments form a sequence of property value pairs, specifying default property values for buttons with this type (a button’s type may be set by giving it a type property when creating the button, using the :type keyword argument).

加えて、nameがデフォルトプロパティ値を継承するボタンタイプ指定するために、キーワード引数:supertypeを使用できる。この継承は、nameの定義時のみ発生することに注意。その後にsupertypeに行われた変更は、そのsubtypeには反映されない。

define-button-typeを使用してボタンのデフォルトプロパティを定義するのは必須ではありません — 特定のタイプをもたないボタンはビルトインのボタンタイプbuttonを使用します — が推奨されません。これを行うことにより通常はコードがより明快かつ効果的になるからです。

39.19.3 ボタンの作成

ボタンは、ボタン固有の情報を保持するために、オーバーレイプロパティかテキストプロパティを使用して、テキストのリージョンに関連付けられます。これらはすべて、そのボタンのタイプ(デフォルトはビルトインのボタンタイプbutton)から初期化されます。すべてのEmacsテキストと同様、ボタンの外観はfaceプロパティにより制御されます。(ボタンタイプbuttonから継承されたfaceプロパティを通じることにより)デフォルトでは典型的なウェブページリンクのような、シンプルなアンダーラインです。

簡便さのために2種類のボタン作成関数があります。1つはバッファーの既存リージョンにボタンプロパティを追加する、make-...buttonと呼ばれる関数と、ボタンテキストを挿入するinsert-...buttonと呼ばれる関数です。

すべてのボタン作成関数は、&rest引数のpropertiesを受け取ります。これはボタンに追加するプロパティを指定する、property valueペアーのシーケンスである必要があります。ボタンのプロパティを参照してください。これに加えて、他のプロパティの継承元となるボタンタイプの指定に、キーワード引数:typeを使用できます。ボタンのタイプを参照してください。作成の間に明示的に指定されなかったプロパティは、(そのタイプがそのようなプロパティを定義していれば)そのボタンのタイプから継承されます。

以下の関数は、ボタンプロパティを保持するために、オーバーレイを使用してボタンを追加します(オーバーレイを参照)。

Function: make-button beg end &rest properties: これはカレントバッファー内のbegからendにボタンを作成して、それをリターンする。

Function: insert-button label &rest properties: これはポイント位置にラベルlabelのボタンを挿入して、それをリターンする。

以下の関数も同様ですが、ボタンプロパティを保持するためにテキストプロパティを使用します(テキストのプロパティを参照)。この種のボタンはバッファーにマーカーを追加せず、非常に多数のボタンが存在しても、バッファーでの編集が低速になることはありません。しかしそのテキストに既存のfaceテキストプロパティが存在する場合(たとえばFont Lockモードにより割り当てられたフェイス)、そのボタンのフェイスは可視にならないかもしれません。これらの関数はいずれも、新たなボタンの開始位置をリターンします。

Function: make-text-button beg end &rest properties: これはテキストプロパティを使用して、カレントバッファー内のbegからendにボタンを作成する。

Function: insert-text-button label &rest properties: これはテキストプロパティを使用して、ポイント位置にラベルlabelのボタンを挿入する。

39.19.4 ボタンの操作

ボタンのプロパティの取得、およびセットを行う関数が存在します。これらは何を行うかを判断するために、ボタンが呼び出す価数によりよく使用される関数です。

buttonパラメーターが指定された場合は、オーバーレイ(オーバーレイボタンの場合)、またはバッファー位置やマーカー(テキストプロパティボタンの場合)いずれかの、特定のボタンを参照するオブジェクトを意味します。そのようなオブジェクトは、ボタンが関数を呼び出す際に1つ目の引数として渡されます。

Function: button-start button: buttonが開始される位置をリターンする。

Function: button-end button: buttonが終了する位置をリターンする。

Function: button-get button prop: ボタンbuttonのpropという名前のプロパティを取得する。

Function: button-put button prop val: buttonのpropプロパティにvalをセットする。

Function: button-activate button &optional use-mouse-action: buttonのactionプロパティを呼び出す(単一の引数buttonを渡して、そのプロパティの値である関数を呼び出す)。use-mouse-actionが非nilなら、actionのかわりにそのボタンのmouse-actionプロパティの呼び出しを試みる。ボタンがmouse-actionプロパティをもたなければ、通常どおりactionを使用する。

Function: button-label button: buttonのテキストラベルをリターンする。

Function: button-type button: buttonのボタンタイプをリターンする。

Function: button-has-type-p button type: buttonがボタンタイプtype、またはtypeのsubtypeのいずれかをもつならtをリターンする。

Function: button-at pos: カレントバッファー内の位置posにあるボタン、またはnilをリターンする。posにあるボタンがテキストプロパティボタンなら、リターン値はposを指すマーカーとなる。

Function: button-type-put type prop val: ボタンタイプtypeのpropプロパティに、valをセットする。

Function: button-type-get type prop: ボタンタイプtypeの、propという名前のプロパティを取得する。

Function: button-type-subtype-p type supertype: ボタンタイプtypeがsupertypeのsubtypeなら、tをリターンする。

39.19.5 ボタンのためのバッファーコマンド

Emacsバッファー内に、ボタンの配置や操作を行うコマンドや関数が存在します。

push-button is the command that a user uses to actually push a button, and is bound by default in the button itself to RET and to mouse-2 using a local keymap in the button’s overlay or text properties. Commands that are useful outside the buttons itself, such as forward-button and backward-button are additionally available in the keymap stored in button-buffer-map; a mode which uses buttons may want to use button-buffer-map as a parent keymap for its keymap.

If the button has a non-nil follow-link property, and mouse-1-click-follows-link is set, a quick mouse-1 click will also activate the push-button command. See section クリック可能なテキストの定義.

Command: push-button &optional pos use-mouse-action: 位置posにあるボタンが指定するアクションを行う。posはバッファー位置、またはマウスイベントのいずれか。use-mouse-actionが非nil、またはposがマウスイベントなら、actionのかわりにそのボタンのmouse-actionプロパティの呼び出しを試み、ボタンにmouse-actionプロパティがなければ、通常のようにactionを使用する。push-buttonがマウスイベントの結果としてインタラクティブに呼び出されたときはそのマウスイベントの位置、それ以外ではポイントの位置が、posのデフォルトになる。posにボタンがなければ何もせずにnilをリターンし、それ以外ならtをリターンする。

Command: forward-button n &optional wrap display-message: 次のn番目、nが負なら前のn番目のボタンに移動する。nが0なら、ポイント位置にある任意のボタンの開始に移動する。wrapが非nilなら、バッファーの先頭または終端を超えて、もう一方の端へ移動を継続する。display-messageが非nilなら、そのボタンのhelp-echo文字列が表示される。非nilのskipプロパティをもつボタンは、すべてスキップされる。見つかったボタンをリターンする。

Command: backward-button n &optional wrap display-message: 前のn番目、nが負なら次のn番目のボタンに移動する。nが0なら、ポイント位置にある任意のボタンの開始に移動する。wrapが非nilなら、バッファーの先頭または終端を超えて、もう一方の端へ移動を継続する。display-messageが非nilなら、そのボタンのhelp-echo文字列が表示される。非nilのskipプロパティをもつボタンは、すべてスキップされる。見つかったボタンをリターンする。

Function: next-button pos &optional count-current
Function: previous-button pos &optional count-current: カレントバッファー内の位置posの次(next-buttonの場合)、または前(previous-buttonの場合)のボタンをリターンする。count-currentが非nilなら、次のボタンから検索を開始するかわりに、posにある任意のボタンを考慮する。

39.20 抽象的なディスプレー

The Ewoc package constructs buffer text that represents a structure of Lisp objects, and updates the text to follow changes in that structure. This is like the “view” component in the “model–view–controller” design paradigm. Ewoc means “Emacs’s Widget for Object Collections”.

ewocは特定のLispデータを表現するバッファーテキストの構築に要される情報を組織化します。ewocのバッファーテキストは順番に、まず固定されたheaderテキスト、次に一連のデータ要素のテキスト記述(あなたが指定するLispオブジェクト)、最後に固定されたfooterテキストという、3つのパートをもっています。具体的には、ewocは以下の情報を含んでいます:

そのテキストが生成されたバッファー。
バッファー内でのそのテキストの開始位置。
ヘッダー文字列とフッター文字列。
2重リンクされたノード(nodes)のチェーン。各ノードは以下を含む:
- データ要素(data element)。単一のLispオブジェクトである。
- そのチェーン内で先行および後続するノードへのリンク。
カレントバッファー内にデータ要素値のテキスト表現を挿入する責務をもつ、pretty-printer関数。

通常はewoc-createによりewocを定義して、その結果のewoc構造体内にノードを構築するために、それをEwocパッケージ内の別の関数に渡してバッファー内に表示します。バッファー内でこれが一度表示されれば、他の関数はバッファー位置とノードの対応を判断したり、あるノードのテキスト表現から別のノードのテキスト表現への移動等を行います。抽象ディスプレーの関数を参照してください。

ノードは、変数が値を保持するのと同じ方法で、データ要素をカプセル化(encapsulate)します。カプセル化は通常、ewocへのノード追加の一部として発生します。以下のように、データ要素値を取得して、その場所に新たな値を配置することができます:

(ewoc-data node)
⇒ value

(ewoc-set-data node new-value)
⇒ new-value

You can also use, as the data element value, a Lisp object (list or vector) that is a container for the real value, or an index into some other structure. The example (see section 抽象ディスプレーの例) uses the latter approach.

データが変更された際には、バッファー内のテキストを更新したいでしょう。ewoc-refresh呼び出しにより全ノード、ewoc-invalidateを使用して特定のノード、またはewoc-mapを使用して述語を満足するすべてのノードを更新できます。あるいは、ewoc-deleteを使用して無効なノードを削除したり、その場所に新たなノードを追加できます。ewocからのノード削除は、バッファーからそれに関連付けられたテキスト記述も同様に削除します。

39.20.1 抽象ディスプレーの関数

このセクションでは、ewocとnodeは上述(抽象的なディスプレーを参照)の構造体を、dataはデータ要素として使用される任意のLispオブジェクトを意味します。

Function: ewoc-create pretty-printer &optional header footer nosep

これは、ノード(とデータ要素)をもたない新たなewocを構築してリターンする。pretty-printerは1つの引数をとる関数であること。この引数は当該ewoc内で使用を計画する類のデータ要素であり、insertを使用してポイント位置にそのテキスト記述を挿入する(Ewocパッケージの内部的メカニズムと干渉するためinsert-before-markersは決して使用しない)。

Normally, a newline is automatically inserted after the header, the footer and every node’s textual description. If nosep is non-nil, no newline is inserted. This may be useful for displaying an entire ewoc on a single line, for example, or for making nodes invisible by arranging for pretty-printer to do nothing for those nodes.

ewocは作成時にカレントだったバッファー内のテキストを保守するので、ewoc-create呼び出し前に意図するバッファーへ切り替えること。

Function: ewoc-buffer ewoc: これは、ewocがそのテキストを保守するバッファーをリターンする。

Function: ewoc-get-hf ewoc: これは、ewocのヘッダーとフッターから作成された、コンスセル(header . footer)をリターンする。

Function: ewoc-set-hf ewoc header footer: これは、ewocのヘッダーおよびフッターに、文字列headerおよびfooterをセットする。

Function: ewoc-enter-first ewoc data
Function: ewoc-enter-last ewoc data: これらはそれぞれ、dataを新たなノードにカプセル化して、それをewocのチェーンノードの先頭または終端に配置する。

Function: ewoc-enter-before ewoc node data
Function: ewoc-enter-after ewoc node data: これらはそれぞれ、dataを新たなノードにカプセル化して、それをewocのnodeの前または後に追加する。

Function: ewoc-prev ewoc node
Function: ewoc-next ewoc node: これらはそれぞれ、ewoc内のnodeの前、または次のノードをリターンする。

Function: ewoc-nth ewoc n: これは、ewoc内で0基準のインデックスnで見つかったノードをリターンする。負のnは、終端から数えることを意味する。nが範囲外なら、ewoc-nthはnilをリターンする。

Function: ewoc-data node: これは、nodeにカプセル化されたデータを抽出して、それをリターンする。

Function: ewoc-set-data node data: これは、nodeにカプセル化されるデータとして、dataをセットする。

Function: ewoc-locate ewoc &optional pos guess: これはポイント(指定された場合はpos)を含むewoc内のノードを判断して、そのノードをリターンする。ewocがノードをもたなければ、nilをリターンする。posが最初のノードの前なら最初のノード、最後のノードの後なら最後のノードをリターンする。オプションの3つ目の引数guessは、pos近傍にあると思われるノードであること。これは結果を変更しないが、関数の実行を高速にする。

Function: ewoc-location node: これは、nodeの開始位置をリターンする。

Function: ewoc-goto-prev ewoc arg
Function: ewoc-goto-next ewoc arg: これらはそれぞれ、ewoc内の前、または次のarg番目のノードにポイントを移動する。すでに最初のノードにポイントがある場合、またはewocが空の場合、ewoc-goto-prevは移動しない。またewoc-goto-nextが最後のノードを超えて移動した場合、結果はnilとなる。この特殊なケースを除き、これらの関数は移動先のノードをリターンする。

Function: ewoc-goto-node ewoc node: これは、ewoc内のnodeの開始にポイントを移動する。

Function: ewoc-refresh ewoc: この関数は、ewocのテキストを再生成する。これはヘッダーとフッターの間のテキスト、すなわちすべてのデータ要素の表現を削除して、各ノードにたいして1つずつ順にpretty-printer関数を呼び出すことによりすることにより機能する。

Function: ewoc-invalidate ewoc &rest nodes: これはewoc-refreshと似ているが、ewoc内のノードセット全体ではなく、nodesだけを対象とする点が異なる。

Function: ewoc-delete ewoc &rest nodes: これは、ewocからnodes内の各要素を削除する。

Function: ewoc-filter ewoc predicate &rest args: これはewoc内の各データ要素にたいしてpredicateを呼び出し、predicateがnilをリターンしたノードを削除する。任意のargsを、predicateに渡すことができる。

Function: ewoc-collect ewoc predicate &rest args: これはewoc内の各データ要素にたいしてpredicateを呼び出し、predicateが非nilをリターンしたノードのリストをリターンする。リスト内の要素は、そのバッファー内での順序になる。任意のargsを、predicateに渡すことができる。

Function: ewoc-map map-function ewoc &rest args: これはewoc内の各データ要素にたいしてmap-functionを呼び出し、map-functionが非nilをリターンしたノードを更新する。任意のargsを、map-functionに渡すことができる。

39.20.2 抽象ディスプレーの例

Here is a simple example using functions of the ewoc package to implement a color components display, an area in a buffer that represents a vector of three integers (itself representing a 24-bit RGB value) in various ways.

(setq colorcomp-ewoc nil
      colorcomp-data nil
      colorcomp-mode-map nil
      colorcomp-labels ["Red" "Green" "Blue"])

(defun colorcomp-pp (data)
  (if data
      (let ((comp (aref colorcomp-data data)))
        (insert (aref colorcomp-labels data) "\t: #x"
                (format "%02X" comp) " "
                (make-string (ash comp -2) ?#) "\n"))
    (let ((cstr (format "#%02X%02X%02X"
                        (aref colorcomp-data 0)
                        (aref colorcomp-data 1)
                        (aref colorcomp-data 2)))
          (samp " (sample text) "))
      (insert "Color\t: "
              (propertize samp 'face
                          `(foreground-color . ,cstr))
              (propertize samp 'face
                          `(background-color . ,cstr))
              "\n"))))

(defun colorcomp (color)
  "新たなバッファー内でCOLORの編集を許可する。
そのバッファーはColor Componentsモードになる。"
  (interactive "sColor (name or #RGB or #RRGGBB): ")
  (when (string= "" color)
    (setq color "green"))
  (unless (color-values color)
    (error "No such color: %S" color))
  (switch-to-buffer
   (generate-new-buffer (format "originally: %s" color)))
  (kill-all-local-variables)
  (setq major-mode 'colorcomp-mode
        mode-name "Color Components")
  (use-local-map colorcomp-mode-map)
  (erase-buffer)
  (buffer-disable-undo)
  (let ((data (apply 'vector (mapcar (lambda (n) (ash n -8))
                                     (color-values color))))
        (ewoc (ewoc-create 'colorcomp-pp
                           "\nColor Components\n\n"
                           (substitute-command-keys
                            "\n\\{colorcomp-mode-map}"))))
    (set (make-local-variable 'colorcomp-data) data)
    (set (make-local-variable 'colorcomp-ewoc) ewoc)
    (ewoc-enter-last ewoc 0)
    (ewoc-enter-last ewoc 1)
    (ewoc-enter-last ewoc 2)
    (ewoc-enter-last ewoc nil)))

This example can be extended to be a color selection widget (in other words, the “controller” part of the “model–view–controller” design paradigm) by defining commands to modify colorcomp-data and to finish the selection process, and a keymap to tie it all together conveniently.

(defun colorcomp-mod (index limit delta)
  (let ((cur (aref colorcomp-data index)))
    (unless (= limit cur)
      (aset colorcomp-data index (+ cur delta)))
    (ewoc-invalidate
     colorcomp-ewoc
     (ewoc-nth colorcomp-ewoc index)
     (ewoc-nth colorcomp-ewoc -1))))

(defun colorcomp-R-more () (interactive) (colorcomp-mod 0 255 1))
(defun colorcomp-G-more () (interactive) (colorcomp-mod 1 255 1))
(defun colorcomp-B-more () (interactive) (colorcomp-mod 2 255 1))
(defun colorcomp-R-less () (interactive) (colorcomp-mod 0 0 -1))
(defun colorcomp-G-less () (interactive) (colorcomp-mod 1 0 -1))
(defun colorcomp-B-less () (interactive) (colorcomp-mod 2 0 -1))

(defun colorcomp-copy-as-kill-and-exit ()
  "color componentsをkillリングにコピーしてバッファーをkill。
文字列は#RRGGBB(6桁16進が付加されたハッシュ)にフォーマットされる。"
  (interactive)
  (kill-new (format "#%02X%02X%02X"
                    (aref colorcomp-data 0)
                    (aref colorcomp-data 1)
                    (aref colorcomp-data 2)))
  (kill-buffer nil))

(setq colorcomp-mode-map
      (let ((m (make-sparse-keymap)))
        (suppress-keymap m)
        (define-key m "i" 'colorcomp-R-less)
        (define-key m "o" 'colorcomp-R-more)
        (define-key m "k" 'colorcomp-G-less)
        (define-key m "l" 'colorcomp-G-more)
        (define-key m "," 'colorcomp-B-less)
        (define-key m "." 'colorcomp-B-more)
        (define-key m " " 'colorcomp-copy-as-kill-and-exit)
        m))

わたしたちが決して各ノード内のデータを変更していないことに注意してください。それらのデータはewoc作成時にnil、または実際のカラーコンポーネントであるベクターcolorcomp-dataにたいするインデックスに固定されています。

39.21 カッコの点滅

このセクションでは、ユーザーが閉カッコを挿入した際に、マッチする開カッコをEmacsが示すメカニズムを説明します。

Variable: blink-paren-function: この変数の値は、閉カッコ構文(close parenthesis syntax)の文字が挿入された際に、常に呼び出される関数(引数なし)であること。blink-paren-functionの値はnilも可能で、この場合は何も行わない。

User Option: blink-matching-paren: この変数がnilなら、blink-matching-openは何も行わない。

User Option: blink-matching-paren-distance: この変数は、ギブアップする前にマッチするカッコをスキャンする、最大の距離を指定する。

User Option: blink-matching-delay: この変数は、マッチするカッコを示し続ける秒数を指定する。分数の秒もよい結果をもたらすことがあるが、デフォルトはすべてのシステムで機能する1である。

Command: blink-matching-open

この関数は、blink-paren-functionのデフォルト値である。この関数は、閉カッコ構文の文字の後にポイントがあると仮定し、マッチする開カッコに瞬時適切な効果を適用する。その文字がまだスクリーン上になければ、エコーエリア内にその文字のコンテキストを表示する。長い遅延を避けるために、この関数は文字数blink-matching-paren-distanceより遠くを検索しない。

以下は、この関数を明示的に呼び出す例である。

(defun interactive-blink-matching-open ()
  "ポイント前のカッコによるsexp開始を瞬時示す"
  (interactive)

  (let ((blink-matching-paren-distance
         (buffer-size))
        (blink-matching-paren t))
    (blink-matching-open)))

39.22 文字の表示

このセクションでは、文字がEmacsにより実際に表示される方法について説明します。文字は通常グリフ(glyph)として表示されます。グリフとは、スクリーン上で1文字の位置を占めるグラフィカルなシンボルであり、その外観はその文字自身に対応します。たとえば文字‘a’(文字コード97)は、‘a’と表示されます。しかし、いくつかの文字は特別な方法で表示されます。たとえば、改頁文字(文字コード12)は、通常は2つのグリフのシーケンス‘^L’で表示され、改行文字(文字コード10)は新たなスクリーン行を開始します。

ディスプレイテーブル(display table)を定義することにより、各文字が表示される方法を変更できます。これはそれぞれの文字を、グリフのシーケンスにマップするテーブルです。ディスプレーテーブルを参照してください。

39.22.1 通常の表示の慣習

以下は、各文字コードの表示にたいする慣習です(ディスプレイテーブルが存在しなければ、これらの慣習をオーバーライドできる。ディスプレーテーブル)を参照されたい)。

コード32から126のプリント可能ASCII文字(printable ASCII characters: 数字、英文字、および‘#’のようなシンボル)は、文字通りそのまま表示される。
タブ文字(文字コード9)は、次のタブストップ列まで伸長された空白文字として表示される。Text Display in The GNU Emacs Manualを参照のこと。変数tab-widthは、タブストップごとのスペース数を制御する(以下参照)。
改行文字(文字コード10)は特殊効果をもつ。これは先行する行を終端して、新たな行を開始する。
非プリント可能ASCII制御文字(ASCII control characters) — 文字コード0から31とDEL文字(文字コード127) — は、変数ctl-arrowに応じて2つの方法のいずれかで表示される。この変数が非nil(デフォルト)なら、たとえばDELにたいしては‘^?’のように、これらの文字は1つ目のグリフが‘^’(‘^’のかわりに使用する文字をディスプレイテーブルで指定できる)のような、2つのグリフのシーケンスとして表示される。
ctl-arrowがnilなら、これらの文字は8進エスケープとして表示される(以下参照)。

このルールは、バッファー内に復帰文字(CR: carriage return、文字コード13)があれば、それにも適用される。しかし復帰文字は、通常はバッファーテキスト内には存在しない。これらは、行末変換(end-of-line conversion)の一部として除去される(コーディングシステムの基本概念を参照)。
rawバイト(raw bytes)とは、コード128から255の非ASCII文字である。これらの文字は8進エスケープ(octal escapes)として表示される。これは1つ目が‘\’にたいするASCIIコードのグリフで、残りがその文字のコードを8進で表した数字である(ディスプレイテーブルで‘\’のかわりに使用するグリフを指定できる)。
255を超える非ASCII文字は、端末がサポートしていればそのまま表示される。端末がサポートしない場合、その文字はグリフなし(glyphless)と呼ばれ、通常はプレースホルダーグリフを使用して表示される。たとえば、ある文字にたいしてグラフィカル端末がフォントをもたなければ、Emacsは通常は16進文字コードを含むボックスを表示する。グリフ文字の表示を参照のこと。

上記の表示慣習は、たとえディスプレイテーブルがあっても、アクティブディスプレイテーブル内のエントリーがnilであるような、すべての文字にたいして適用されます。したがってディスプレイテーブルのセットアップ時に指定が必要なのは、特別な振る舞いを望む文字だけです。

以下の変数は、スクリーン上で特定の文字が表示される方法に影響します。これらはその文字が占める列数を変更するので、インデント関数にも影響を与えます。また、モードラインが表示される方法にも影響があります。新たな値を使用してモードラインを強制的に再表示するには、関数force-mode-line-updateを呼び出してください(モードラインのフォーマットを参照)。

User Option: ctl-arrow: このバッファーローカル変数は、コントロール文字が表示される方法を制御する。非nilなら‘^A’のようにカレットとその文字のように表示され、nilなら‘\001’のようにバックスラッシュと8進3桁のように8進エスケープとして表示される。

User Option: tab-width: このバッファーローカル変数の値は、Emacsバッファー内でのタブ文字表示で使用する、タブストップ間のスペース数である。値は列単位で、デフォルトは8。この機能は、コマンドtab-to-tab-stopで使用される、ユーザー設定可能なタブストップとは完全に無関係であることに注意。Adjustable Tab Stopsを参照のこと。

39.22.2 ディスプレーテーブル

ディスプレイテーブルとは、サブタイプとしてdisplay-tableをもつ特殊用途の文字テーブル(文字テーブル)で、文字の通常の表示慣習をオーバーライドするために使用されます。このセクションではディスプレイテーブルオブジェクトの作成と調査、および要素を割り当てる方法について説明します。

Function: make-display-table: これは、ディスプレイテーブルを作成してリターンする。テーブルは初期状態では、すべての要素にnilをもつ。

ディスプレイテーブルの通常の要素は、文字コードによりインデックス付けされる。インデックスcの要素は、コードcの表示方法を示す。値はnil(これは通常の表示慣習に応じて文字cを表示することを意味する。通常の表示の慣習を参照のこと)、またはグリフコードのベクター(これらのグリフとして文字cを表示することを意味する。グリフを参照のこと)のいずれかであること。

Warning: if you use the display table to change the display of newline characters, the whole buffer will be displayed as one long line.

The display table also has six extra slots which serve special purposes. Here is a table of their meanings; nil in any slot means to use the default for that slot, as stated below.

0: The glyph for the end of a truncated screen line (the default for this is ‘$’). See section グリフ. On graphical terminals, Emacs by default uses arrows in the fringes to indicate truncation, so the display table has no effect, unless you disable the fringes (see Window Fringes in the GNU Emacs Manual).
1: The glyph for the end of a continued line (the default is ‘\’). On graphical terminals, Emacs by default uses curved arrows in the fringes to indicate continuation, so the display table has no effect, unless you disable the fringes.
2: 8進文字コードとして表示される文字を示すグリフ(デフォルトは‘\’)。
3: コントロール文字を示す(デフォルトは‘^’)。
4: 不可視行があることを示すグリフのベクター(デフォルトは‘...’)。選択的な表示を参照のこと。
5: The glyph used to draw the border between side-by-side windows (the default is ‘|’). See section ウィンドウの分割. This currently has effect only on text terminals; on graphical terminals, if vertical scroll bars are supported and in use, a scroll bar separates the two windows, and if there are no vertical scroll bars and no dividers (see section ウィンドウディバイダー), Emacs uses a thin line to indicate the border.

たとえば以下は、関数make-glyph-codeにたいしてctl-arrowに非nilをセットして得られる効果を模倣するディスプレイテーブル(グリフを参照のこと)を構築する例です:

(setq disptab (make-display-table))
(dotimes (i 32)
  (or (= i ?\t)
      (= i ?\n)
      (aset disptab i
            (vector (make-glyph-code ?^ 'escape-glyph)
                    (make-glyph-code (+ i 64) 'escape-glyph)))))
(aset disptab 127
      (vector (make-glyph-code ?^ 'escape-glyph)
              (make-glyph-code ?? 'escape-glyph)))))

Function: display-table-slot display-table slot: この関数は、display-tableのエクストラスロットslotの値をリターンする。引数slotには0から5の数字(両端含む)、またはスロット名(シンボル)を指定できる。有効なシンボルはtruncation、wrap、escape、control、selective-display、vertical-border。

Function: set-display-table-slot display-table slot value: この関数は、display-tableのエクストラスロットslotにvalueを格納する。引数slotには0から5の数字(両端含む)、またはスロット名(シンボル)を指定できる。有効なシンボルはtruncation、wrap、escape、control、selective-display、vertical-border。

Function: describe-display-table display-table: この関数は、ヘルプバッファーにディスプレイテーブルdisplay-tableの説明を表示する。

Command: describe-current-display-table: このコマンドは、ヘルプバッファーにカレントディスプレイテーブルの説明を表示する。

39.22.3 アクティブなディスプレーテーブル

ウィンドウはそれぞれディスプレイテーブルを指定でき、各バッファーもディスプレイテーブルを指定できます。もしウィンドウにディスプレイテーブルがあれば、それはバッファーのディスプレイテーブルより優先されます。ウィンドウとバッファーのいずれもディスプレイテーブルをもたなければ、Emacsは標準的なディスプレイテーブルの使用を試みます。標準ディスプレイテーブルがnilなら、Emacsは通常の文字表示慣習を使用します(通常の表示の慣習を参照)。

ディスプレイテーブルはモードラインが表示される方法に影響を与えるので、新たなディスプレイテーブルを使用してモードラインを強制的に再表示するには、force-mode-line-updateを使用することに注意してください(モードラインのフォーマットを参照)。

Function: window-display-table &optional window: この関数はwindowのディスプレイテーブル、ディスプレイテーブルがなければnilをリターンする。windowのデフォルトは、選択されたウィンドウ。

Function: set-window-display-table window table: この関数は、windowのディスプレイテーブルにtableをセットする。引数tableはディスプレイテーブル、またはnilのいずれかであること。

Variable: buffer-display-table: この変数は、すべてのバッファーにおいて自動的にバッファーローカルになる。変数の値は、そのバッファーのディスプレイテーブルを指定する。これがnilなら、バッファーのディスプレイテーブルは存在しない。

Variable: standard-display-table: The value of this variable is the standard display table, which is used when Emacs is displaying a buffer in a window with neither a window display table nor a buffer display table defined, or when Emacs is outputting text to the standard output or error streams. Although its default is typically nil, in an interactive session if the terminal cannot display curved quotes, its default maps curved quotes to ASCII approximations. See section Text Quoting Style.

disp-tableライブラリーでは、標準ディスプレイテーブルを変更するために、いくつかの関数を定義されています。

39.22.4 グリフ

グリフ(glyph)とは、スクリーン上で1文字を占めるグラフィカルなシンボルです。各グリフはLisp内でグリフコード(glyph code)として表現されます。これは文字と、オプションで表示するフェイスを指定します(フェイスを参照)。ディスプレイテーブル内のエントリーとしての使用が、グリフコードの主な用途です(ディスプレーテーブルを参照)。以下の関数は、グリフコードを操作するために使用されます:

Function: make-glyph-code char &optional face: この関数は、文字charを表すグリフを、フェイスfaceでリターンする。faceが省略またはnilならグリフはデフォルトフェイスを使用し、その場合にはグリフコードは整数である。faceが非nilなら、グリフコードが整数オブジェクトである必要はない。

Function: glyph-char glyph: この関数は、グリフコードglyphの文字をリターンする。

Function: glyph-face glyph: この関数は、グリフコードglyphのフェイス、またはglyphがデフォルトフェイスを使用する場合はnilをリターンする。

テキスト端末上で実際にどのようにグリフコードを表示するかを変更するために、glyph tableをセットアップできる。この機能は半ば時代遅れであり、かわりにglyphless-char-displayを使用すること(グリフ文字の表示を参照)。

Variable: glyph-table

この変数の値が非nilなら、それはカレントグリフテーブルである。これは文字端末上でのみ効果があり、グラフィカルディスプレイ上ではすべてのグリフはそのままliteralに表示される。グリフテーブルは、g番目の要素がグリフコードgの表示方法を指定するようなベクターであること。ここでgはフェイス未指定なグリフにたいするグリフコードである。要素はそれぞれ、以下のいずれかであること:

nil: そのグリフをそのままliteralに表示する。
文字列: 指定された文字列を端末に送信することにより、そのグリフを表示する。
グリフコード: 指定されたグリフコードをかわりに表示する。

グリフテーブルのテーブル長以上の整数グリフコードは、そのままliteralに表示される。

39.22.5 グリフ文字の表示

グリフ無し文字(glyphless characters)とは、literalに表示されるのではなく特別な方法、すなわち16進コードを中に含むボックスとして表示される文字です。これらの文字には、グリフが無いと明示的に定義された文字や、利用可能なフォントがない文字(グラフィカルなディスプレイ)、その端末のコーディングシステムではエンコードできない文字(テキスト端末)が同様に含まれます。

Variable: glyphless-char-display

この変数の値はグリフ無し文字と、それらの表示方法を定義する文字テーブルである。エントリーはそれぞれ、以下の表示メソッドのいずれかでなければならない:

nil: 通常の方法でその文字を表示する。
zero-width: その文字を表示しない。
thin-space: グラフィカルな端末では幅が1ピクセル、テキスト端末では幅が1文字の狭いスペース。
empty-box: 空のボックスを表示する。
hex-code: その文字のUnicodeコードポイントの16進表記を含むボックスを表示する。
ASCII文字列: Display a box containing that string. The string should contain at most 6 ASCII characters.
コンスセル (graphical . text): グラフィカルな端末ではgraphical、テキスト端末ではtextで表示する。graphicalとtextはいずれも、上述した表示メソッドのいずれかでなければならない。

The thin-space, empty-box, hex-code, and ASCII string display methods are drawn with the glyphless-char face. On text terminals, a box is emulated by square brackets, ‘[]’.

文字テーブルには、利用可能なすべてのフォントでも表示できない、またはその端末のコーディングシステムでエンコードできないすべての文字の表示方法を定義する、余分なスロットが1つある。その値は、上述した表示メソッドのうちzero-widthとコンスセル以外のいずれかでなければならない。

アクティブなディスプレイテーブル内に非nilなエントリーをもつ文字では、そのディスプレイテーブルが効果をもつ。この場合、Emacsはglyphless-char-displayをまったく参照しない。

User Option: glyphless-char-display-control

このユーザーオプションは、似かよった文字のグループにたいしてglyphless-char-displayをセットする便利な手段を提供する。Lispコードから、この値を直接セットしてはならない。glyphless-char-display更新する、カスタム関数:setを通じた場合のみ、その値は効果をもつ。

この値は、要素が(group . method)であるようなalistであること。ここでgroupは文字びグループを指定するシンボル、methodはそれらを表示する方法を指定するシンボルである。

groupは以下のいずれかであること:

c0-control: 改行文字とタブ文字を除くU+0000からU+001FまでのASCIIコントロール文字(通常は‘^A’のようなエスケープシーケンスとして表示される。How Text Is Displayed in The GNU Emacs Manualを参照されたい)。
c1-control: U+0080からU+009Fまでの非ASCII、非プリント文字(通常は‘\230’のような8進エスケープシーケンスとして表示される)。
format-control: Characters of Unicode General Category [Cf], such as ‘U+200E’ (Left-to-Right Mark), but excluding characters that have graphic images, such as ‘U+00AD’ (Soft Hyphen).
no-font: Characters for which there is no suitable font, or which cannot be encoded by the terminal’s coding system.

methodシンボルはzero-width、thin-space、empty-box、hex-codeのいずれかであること。これらは上述のglyphless-char-displayでの場合と同様の意味をもつ。

39.23 ビープ

このセクションでは、ユーザーの注意を喚起するために、Emacsでベルを鳴らす方法を説明します。これを行う頻度は控え目にしてください。頻繁なベルは刺激過剰になる恐れがあります。。同様に、エラーのシグナル時に過度にビープ音を使用しないよう注意してください。

Function: ding &optional do-not-terminate: この関数はビープ音を鳴らす、またはスクリーンをフラッシュする(後述のvisible-bellを参照)。do-not-terminateがnilなら、この関数はカレントで実行中のキーボードマクロも終了する。

Function: beep &optional do-not-terminate: これはdingのシノニムである。

User Option: visible-bell: この変数は、ベルを表すためにスクリーンをフラッシュすべきかどうかを決定する。非nilならフラッシュし、nilならフラッシュしない。これはグラフィカルなディスプレイで効果的であり、テキスト端末ではその端末のTermcapエントリーが可視ベル(visible bell) ‘vb’の能力を定義する。

User Option: ring-bell-function: If this is non-nil, it specifies how Emacs should ring the bell. Its value should be a function of no arguments. If this is non-nil, it takes precedence over the visible-bell variable.

39.24 ウィンドウシステム

Emacsは複数のウィンドウシステムで機能しますが、特にXウィンドウシステムにおいてもっとも機能します。EmacsとXはどちらも“ウィンドウ”を使用しますが、異なる使い方をします。Emacsのフレームは、Xにおいては単一のウィンドウです。Emacsの個々のウィンドウについては、Xはまったく関知しません。

Variable: window-system

この端末ローカルな変数は、Emacsがフレームを表示するのに、何のウィンドウシステムを使用しているかを示す。可能な値は、

x: EmacsはXを使用してフレームを表示している。
w32: EmacsはネイティブMS-Windows GUIを使用してフレームを表示している。
ns: Emacs is displaying the frame using the Nextstep interface (used on GNUstep and macOS).
pc: EmacsはMS-DOSのスクリーン直接書き込みを使用してフレームを表示している。
nil: Emacsは文字ベース端末を使用してフレームを表示している。

Variable: initial-window-system: This variable holds the value of window-system used for the first frame created by Emacs during startup. (When Emacs is invoked as a daemon, it does not create any initial frames, so initial-window-system is nil, except on MS-Windows, where it is still w32. See daemon in The GNU Emacs Manual.)

Function: window-system &optional frame: この関数は、frameを表示するために使用されているウィンドウシステムを示す名前のシンボルをリターンする。この関数がリターンし得るシンボルのリストは、変数window-systemの記述と同様である。

テキスト端末とグラフィカルなディスプレイで異なる処理を行うコードを記述したいときは、window-systemとinitial-window-systemを、述語やブーリーンフラグ変数としてnot使用しないでください。これは、与えられたディスプレイタイプでのEmacsの能力指標として、window-systemが適していないからです。かわりにdisplay-graphic-p、またはディスプレー機能のテストで説明しているその他の述語display-*-pを使用してください。

39.25 Tooltips

Tooltips are special frames (see section フレーム) that are used to display helpful hints (a.k.a. “tips”) related to the current position of the mouse pointer. Emacs uses tooltips to display help strings about active portions of text (see section 特殊な意味をもつプロパティ) and about various UI elements, such as menu items (see section 拡張メニューアイテム) and tool-bar buttons (see section ツールバー).

Function: tooltip-mode: Tooltip Mode is a minor mode that enables display of tooltips. Turning off this mode causes the tooltips be displayed in the echo area. On text-mode (a.k.a. “TTY”) frames, tooltips are always displayed in the echo area.

When Emacs is built with GTK+ support, it by default displays tooltips using GTK+ functions, and the appearance of the tooltips is then controlled by GTK+ settings. GTK+ tooltips can be disabled by changing the value of the variable x-gtk-use-system-tooltips to nil. The rest of this subsection describes how to control non-GTK+ tooltips, which are presented by Emacs itself.

Tooltips are displayed in special frames called tooltip frames, which have their own frame parameters (see section フレームのパラメーター). Unlike other frames, the default parameters for tooltip frames are stored in a special variable.

User Option: tooltip-frame-parameters: This customizable option holds the default frame parameters used for displaying tooltips. Any font and color parameters are ignored, and the corresponding attributes of the tooltip face are used instead. If left or top parameters are included, they are used as absolute frame-relative coordinates where the tooltip should be shown. (Mouse-relative position of the tooltip can be customized using the variables described in Tooltips in The GNU Emacs Manual.) Note that the left and top parameters, if present, override the values of mouse-relative offsets.

The tooltip face determines the appearance of text shown in tooltips. It should generally use a variable-pitch font of size that is preferably smaller than the default frame font.

Variable: tooltip-functions: This abnormal hook is a list of functions to call when Emacs needs to display a tooltip. Each function is called with a single argument event which is a copy of the last mouse movement event. If a function on this list actually displays the tooltip, it should return non-nil, and then the rest of the functions will not be called. The default value of this variable is a single function tooltip-help-tips.

If you write your own function to be put on the tooltip-functions list, you may need to know the buffer of the mouse event that triggered the tooltip display. The following function provides that information.

Function: tooltip-event-buffer event: This function returns the buffer over which event occurred. Call it with the argument of the function from tooltip-functions to obtain the buffer whose text triggered the tooltip. Note that the event might occur not over a buffer (e.g., over the tool bar), in which case this function will return nil.

Other aspects of tooltip display are controlled by several customizable settings; see Tooltips in The GNU Emacs Manual.

39.26 双方向テキストの表示

Emacsはアラビア語、ペルシア語、ヘブライ語のような、水平方向テキストの自然な表示順がR2L(right-to-left: 右から左)に実行されるようなスクリプトで記述されたテキストを表示できます。さらにL2R(right-to-left: 左から右)のテキストに埋め込まれたR2Lスクリプト(例: プログラムソースファイル内のアラビア語やヘブライ語のコメント)は適宜右から左にR2Lに表示される一方、ラテンスクリプト部やR2Lテキストに埋め込まれた数字はL2Rで表示されます。わたしたちは、そのようなL2RとR2Lが混交されたテキストを双方向テキスト(bidirectional text)と呼びます。このセクションでは、双方向テキストの編集と表示にたいする機能とオプションんついて説明します。

Text is stored in Emacs buffers and strings in logical (or reading) order, i.e., the order in which a human would read each character. In right-to-left and bidirectional text, the order in which characters are displayed on the screen (called visual order) is not the same as logical order; the characters’ screen positions do not increase monotonically with string or buffer position. In performing this bidirectional reordering, Emacs follows the Unicode Bidirectional Algorithm (a.k.a. UBA), which is described in Annex #9 of the Unicode standard (http://www.unicode.org/reports/tr9/). Emacs provides a “Full Bidirectionality” class implementation of the UBA, consistent with the requirements of the Unicode Standard v9.0. Note, however, that the way Emacs displays continuation lines when text direction is opposite to the base paragraph direction deviates from the UBA, which requires to perform line wrapping before reordering text for display.

Variable: bidi-display-reordering

このバッファーローカル変数の値が非nil(デフォルト)なら、Emacsは表示で双方向の並べ替えを行う。この並べ替えはバッファーテキスト、同様に文字列表示やバッファー内のテキストプロパティやオーバーレイプロパティ由来のオーバーレイ文字列に効果を及ぼす(オーバーレイのプロパティおよびdisplayプロパティを参照)。値がnilなら、Emacsはバッファー内での双方向の並べ替えを行わない。

bidi-display-reorderingのデフォルト値は、モードライン内に表示されるテキスト(モードラインのフォーマットを参照)、およびヘッダー行(ウィンドウのヘッダーラインを参照)を含む、バッファーにより直接提供されない文字列の並べ替えを制御する。

たとえバッファーのbidi-display-reorderingが非nilでも、Emacsがユニバイトバッファーのテキストの並べ替えを行うことはありません。これはユニバイトバッファーに含まれるのが文字ではなくrawバイトであり、並べ替えに要する方向的なプロパティを欠くからです。したがって、あるバッファーのテキストが並べ替えられるかどうかテストするには、bidi-display-reorderingのテスト単独では不十分です。正しいテストは以下のようになります:

 (if (and enable-multibyte-characters
          bidi-display-reordering)
     ;; 表示時にバッファーは並べ替えられるだろう
   )

とはいえ、親バッファーが並べ替えられた際には、ユニバイト表示およびオーバーレイ文字列は並べ替えられます。これはEmacsにより、プレーンASCII文字列がユニバイト文字列に格納されるからです。ユニバイト表示またはオーバーレイ文字列が非ASCII文字列を含むなら、それらの文字はL2Rの方向をもつとみなされます。

テキストプロパティdisplay、値が文字列であるようなdisplayプロパティによるオーバーレイ、バッファーテキストを置換するその他任意のプロパティにカバーされたテキストは、表示時の並べ替え時に単一の単位として扱われます。つまり、これらのプロパティにカバーされたテキストのchunk全体が、一緒に並べ替えられます。さらに、そのようなテキストchunk内の文字の双方向的なプロパティは無視され、Emacsはあたかもそれらがオブジェクト置換文字(Object Replacement Character)として知られる単一文字で置換されたかのように、それらを並べ替えます。これは、テキスト範囲上にdisplayプロパティを配すことにより、表示時に周辺テキストを並べ替える方法が変更され得ることを意味しています。このような予期せぬ効果を防ぐには、常に周辺テキストと等しい方向のテキストにたいしてそのようなプロパティを配してください。

双方向テキストのパラグラフはそれぞれ、R2LまたはL2Rいずれかの基本方向(base direction)をもちます。L2Rパラグラフは、そのウィンドウの左マージンを先頭に表示され、そのテキストが右マージンに達したら切り詰め、または継続されます。R2Lパラグラフは、そのウィンドウの右マージンを先頭に表示され、そのテキストが左マージンに達したら切り詰め、または継続されます。

Where exactly paragraphs start and end, for the purpose of the Emacs UBA implementation, is determined by the following two buffer-local variables (note that paragraph-start and paragraph-separate have no influence on this). By default both of these variables are nil, and paragraphs are bounded by empty lines, i.e., lines that consist entirely of zero or more whitespace characters followed by a newline.

Variable: bidi-paragraph-start-re: If non-nil, this variable’s value should be a regular expression matching a line that starts or separates two paragraphs. The regular expression is always matched after a newline, so it is best to anchor it, i.e., begin it with a "^".

Variable: bidi-paragraph-separate-re: If non-nil, this variable’s value should be a regular expression matching a line separates two paragraphs. The regular expression is always matched after a newline, so it is best to anchor it, i.e., begin it with a "^".

If you modify any of these two variables, you should normally modify both, to make sure they describe paragraphs consistently. For example, to have each new line start a new paragraph for bidi-reordering purposes, set both variables to "^".

デフォルトでは、Emacsはテキスト先頭を調べることにより、各パラグラフの基本方向を判断します。基本方向の精細な決定手法はUBAにより指定されており、簡潔に言うとその明示にな方向生をもつそのパラグラフ内の最初の文字が、そのパラグラフの基本方向を決定します。とはいえ、あるバッファーが自身のパラグラフにたいして、特定の基本方向の強制を要する場合もあります。たとえば、プログラムソースコードを含むバッファーは、すべてのパラグラフがL2Rで表示されるよう強制されるべきでしょう。これを行うために、以下の変数を使用できます:

User Option: bidi-paragraph-direction

このバッファーローカル変数の値が、right-to-leftまたはleft-to-rightいずれかのシンボルなら、そのバッファー内のすべてのパラグラフがその指定された方向をもつとみなされる。その他すべての値はnil(デフォルト)と等価であり、各パラグラフの基本方向はその内容により判断されることを意味する。

プログラムソースコードにたいするモードは、これをleft-to-rightにセットすること。Progモードはデフォルトでこれを行うので、Progモードから派生したモードは、これを明示的にセットする必要はない(基本的なメジャーモードを参照)。

Function: current-bidi-paragraph-direction &optional buffer: この関数は、bufferという名前のバッファーのポイント位置のパラグラフ方向をリターンする。リターンされる値は、left-to-rightかright-to-leftいずれかのシンボルである。bufferが省略またはnilの場合のデフォルトは、カレントバッファーである。変数bidi-paragraph-directionのバッファーローカル値が非nilなら、リターンされる値はその値と等しくなるだろう。それ以外なら、リターンされる値はEmacsにより動的に決定されたそのパラグラフの方向を反映する。bidi-display-reorderingの値がnilのバッファー、同様にユニバイトバッファーにたいしては、この関数は常にleft-to-rightをリターンする。

バッファーのカレントのスクリーン位置にたいして、ビジュアル順に、L2RまたはR2Lいずれかの方向へ、厳密なポイント移動を要す場合があります。Emacsはこれを行うためのプリミティブを提供します。

Function: move-point-visually direction

この関数は、そのバッファーにたいしてカレントで選択されたウィンドウのポイントを、スクリーン上ですぐ右または左のポイントへ移動する。directionが正ならスクリーン位置は右へ、それ以外ならスクリーン位置は左へ移動するだろう。周囲の双方向コンテキストに依存して、これは潜在的に多くのバッファーのポイントを移動してしまい得ることに注意。スクリーン行終端で呼び出された場合、この関数はdirectionに応じて適宜、次行または前行の、右端または左端のスクリーン位置にポイントを移動する。

この関数はその値として、新たなバッファー位置をリターンする。

Bidirectional reordering can have surprising and unpleasant effects when two strings with bidirectional content are juxtaposed in a buffer, or otherwise programmatically concatenated into a string of text. A typical problematic case is when a buffer consists of sequences of text fields separated by whitespace or punctuation characters, like Buffer Menu mode or Rmail Summary Mode. Because the punctuation characters used as separators have weak directionality, they take on the directionality of surrounding text. As result, a numeric field that follows a field with bidirectional content can be displayed to the left of the preceding field, messing up the expected layout. There are several ways to avoid this problem:

- 双方向の内容をもち得る各フィールド終端に、スペシャル文字LEFT-TO-RIGHT MARK(略してLRM)のU+200Eを付加する。後述の関数bidi-string-mark-left-to-rightは、この目的に手頃である。(R2LパラグラフではかわりにRIGHT-TO-LEFT MARK、略してRLMのU+200Fを使用する。) これはUBAにより推奨される解決策の1つである。
- フィールドセパレーターにタブ文字を含める。タブ文字は双方向の並べ替えにおいてセグメントセパレーター(segment separator)の役割を演じ、両側のテキストを個別に並べ替えさせる。
- displayプロパティ、または(space . PROPS)という形式の値をもつオーバーレイ(スペースの指定を参照)でフィールドを区切る。Emacsはこのdisplay仕様をパラグラフセパレーター(paragraph separator)として扱い、両側のテキストを個別に並べ替える。

Function: bidi-string-mark-left-to-right string: この関数は、結果を安全に他の文字列に結合できるよう、あるいはこの文字列とスクリーン上で次行となる行に関連するレイアウトを乱すことなく、バッファー内の他の文字列に並置できるよう、自身への引数stringを恐らく変更してリターンする。この関数がリターンする文字列がR2Lパラグラフの一部として表示される文字列なら、それは常に後続するテキストの左に出現するだろう。この関数は自身の引数の文字を検証することにより機能し、もしそれらの文字のいずれかがディスプレイ上の並べ替えを発生し得るなら、この関数はその文字列にLRM文字を付加する。付加されたLRM文字はテキストプロパティinvisibleにtを与えることにより、不可視にできる(不可視のテキストを参照)。

並べ替えアルゴリズムは、bidi-classプロパティとして格納された、その文字の双方向プロパティを使用します(文字のプロパティを参照)。Lispプログラムはput-char-code-property関数を呼び出すことにより、これらのプロパティを変更できます。しかしこれを行うにはUBAの完全な理解が要求されるので、推奨しません。ある文字の双方向プロパティにたいする任意の変更は、グローバルな効果をもちます。これらはEmacsのフレームのすべてのフレームとウィンドウに影響します。

同様に、mirroringプロパティは、並べ替えられたテキスト内の、適切にミラーされた文字の表示に使用されます。Lispプログラムは、このプロパティを変更することにより、ミラーされた表示に影響を与えることができます。繰り返しますが、そのような変更はEmacsのすべての表示に影響を与えます。

The bidirectional properties of characters can be overridden by inserting into the text special directional control characters, LEFT-TO-RIGHT OVERRIDE (LRO) and RIGHT-TO-LEFT OVERRIDE (RLO). Any characters between a RLO and the following newline or POP DIRECTIONAL FORMATTING (PDF) control character, whichever comes first, will be displayed as if they were strong right-to-left characters, i.e. they will be reversed on display. Similarly, any characters between LRO and PDF or newline will display as if they were strong left-to-right, and will not be reversed even if they are strong right-to-left characters.

These overrides are useful when you want to make some text unaffected by the reordering algorithm, and instead directly control the display order. But they can also be used for malicious purposes, known as phishing. Specifically, a URL on a Web page or a link in an email message can be manipulated to make its visual appearance unrecognizable, or similar to some popular benign location, while the real location, interpreted by a browser in the logical order, is very different.

Emacs provides a primitive that applications can use to detect instances of text whose bidirectional properties were overridden so as to make a left-to-right character display as if it were a right-to-left character, or vise versa.

Function: bidi-find-overridden-directionality from to &optional object

This function looks at the text of the specified object between positions from (inclusive) and to (exclusive), and returns the first position where it finds a strong left-to-right character whose directional properties were forced to display the character as right-to-left, or for a strong right-to-left character that was forced to display as left-to-right. If it finds no such characters in the specified region of text, it returns nil.

The optional argument object specifies which text to search, and defaults to the current buffer. If object is non-nil, it can be some other buffer, or it can be a string or a window. If it is a string, the function searches that string. If it is a window, the function searches the buffer displayed in that window. If a buffer whose text you want to examine is displayed in some window, we recommend to specify it by that window, rather than pass the buffer to the function. This is because telling the function about the window allows it to correctly account for window-specific overlays, which might change the result of the function if some text in the buffer is covered by overlays.

When text that includes mixed right-to-left and left-to-right characters and bidirectional controls is copied into a different location, it can change its visual appearance, and also can affect the visual appearance of the surrounding text at destination. This is because reordering of bidirectional text specified by the UBA has non-trivial context-dependent effects both on the copied text and on the text at copy destination that will surround it.

Sometimes, a Lisp program may need to preserve the exact visual appearance of the copied text at destination, and of the text that surrounds the copy. Lisp programs can use the following function to achieve that effect.

Function: buffer-substring-with-bidi-context start end &optional no-properties: This function works similar to buffer-substring (see section バッファーのコンテンツを調べる), but it prepends and appends to the copied text bidi directional control characters necessary to preserve the visual appearance of the text when it is inserted at another place. Optional argument no-properties, if non-nil, means remove the text properties from the copy of the text.

40 オペレーティングシステムのインターフェース

これはEmacsの開始と終了、オペレーティングシステム内の値へのアクセス、端末の入力と出力に関するチャプターです。

関連する情報はEmacsのビルドを参照してください。端末とスクリーンに関連するオペレーティングシステムの状態に関する追加情報は、Emacsのディスプレー表示を参照してください。

40.1 Emacsのスタートアップ		Emacsのスタートアッププロセスのカスタマイズ。
40.2 Emacsからの脱出		(永久または一時的に)exitが機能する方法。
40.3 オペレーティングシステムの環境		システム名と種類の区別。
40.4 ユーザーの識別		そのユーザーの名前とユーザーIDを調べる。
40.5 時刻		カレント時刻の取得。
40.6 Time Zone Rules		Rules for time zones and daylight saving time.
40.7 時刻の変換		時刻の数値形式からカレンダーデータへの変換と逆変換。
40.8 時刻のパースとフォーマット		時刻の数値形式からテキストへの変換と逆変換。
40.9 プロセッサーの実行時間		Emacsによる実行時間の取得。
40.10 時間の計算		時間の加減算、その他。
40.11 遅延実行のためのタイマー		特定時刻に関数を呼び出すためにターマーをセットする。
40.12 アイドルタイマー		Emacsが特定の時間の間アイドル時に関数を呼び出すためにタイマーをセットする。
40.13 端末の入力		端末入力へのアクセスと記録。
40.14 端末の出力		端末出力の制御と記録。
40.15 サウンドの出力		コンピューターのスピーカーでのサウンド再生。
40.16 X11キーシンボルの処理		Xウィンドウにたいするキーシンボルの操作。
40.17 batchモード		端末との対話なしでEmacsを実行する。
40.18 セッションマネージャー		Xセッション管理の保存とリストア。
40.19 デスクトップ通知
40.20 ファイル変更による通知		ファイル通知。
40.21 動的にロードされるライブラリー		サポートライブラリーのオンデマンドロード。
40.22 Security Considerations		Running Emacs in an unfriendly environment.

40.1 Emacsのスタートアップ

このセクションでは、Emacsが開始時に何を行うかと、それらのアクションのカスタマイズ方法を説明します。

40.1.1 要約: スタートアップ時のアクション順序

Emacsは起動時に、以下の処理を行います(startup.el内のnormal-top-levelを参照):

このリストの各ディレクトリー内にあるsubdirs.elという名前のファイルを実行することにより、load-pathにサブディレクトリーを追加する。通常このファイルは、そのディレクトリー内にあるサブディレクトリーをこのリストに追加して、順にそれらをスキャンする。通常、ファイルsubdirs.elは、Emacsインストール時に自動的に作成される。
load-pathのディレクトリー内で見つかった、すべてのleim-list.elをロードする。このファイルは、入力メソッドの登録を意図している。この検索は、ユーザーが作成するかもしれない、個人的なleim-list.elすべてにたいしてのみ行われる。標準的なEmacsライブラリーを含むディレクトリーはスキップされる(これらは単一のleim-list.elだけに含まれるべきであり、Emacs実行形式にコンパイル済である)。
変数before-init-timeに、current-timeの値をセットする(時刻を参照)。これはafter-init-timeにnilをセットすることにより、Emacs初期化時にLispプログラムへの合図も行う。
LANGのような環境変数がそれを要するなら、言語環境と端末のコーディングシステムをセットする。
コマンドライン引数にたいして、いくつかの基本的なパースを行う。
batchモードで実行されていなければ、変数initial-window-systemが指定するウィンドウシステムを初期化する(initial-window-systemを参照)。サポートされる各ウィンドウシステムにたいする初期化関数は、window-system-initialization-alistにより指定される。initial-window-systemの値がwindowsystemなら、ファイルterm/windowsystem-win.el内で適切な初期化関数が定義されている。このファイルはビルド時に、Emacs実行可能形式にコンパイルされているべきである。
ノーマルフックbefore-init-hookを実行する。
If appropriate, it creates a graphical frame. This is not done in batch (noninteractive) or daemon mode.
初期フレームのフェイスを初期化して、必要ならメニューバーとツールバーをセットする。グフィカルなフレームがサポートされていたら、たとえカレントフレームがグラフィカルでなくても、後でグラフィカルなフレームが作成されるかもしれないので、ツールバーをセットアップする。
リストcustom-delayed-init-variables内のメンバーを再初期化するために、custom-reevaluate-settingを使用する。これらのメンバーはデフォルト値が、ビルド時ではなく実行時のコンテキストに依存する、すべての事前ロード済ユーザーオプションである。custom-initialize-delayを参照のこと。
存在する場合はライブラリーsite-startをロードする。これはオプション‘-Q’か‘--no-site-file’が指定された場合は行われない。
ユーザーのinitファイルをロードする(initファイルを参照)。これはオプション‘-q’、‘-Q’、または‘--batch’が指定されていたら行われない。‘-u’オプションが指定された場合、Emacsはかわりにそのユーザーのホームディレクトリー内でinitファイルを探す。
存在する場合はライブラリーdefaultをロードする。これはinhibit-default-initが非nil、あるいはオプション‘-q’、‘-Q’、または‘--batch’指定された場合は行われない。
もしファイルが存在して、かつ読み込み可能なら、abbrev-file-nameで指定されるファイルから、ユーザーのabbrevをロードする(abbrev-file-nameを参照)。オプション‘--batch’が指定されていたら、これは行われない。
It calls the function package-initialize to activate any optional Emacs Lisp package that has been installed. See section パッケージ化の基礎. However, Emacs doesn’t initialize packages when package-enable-at-startup is nil or when it’s started with one of the options ‘-q’, ‘-Q’, or ‘--batch’. To initialize packages in the latter case, package-initialize should be called explicitly (e.g., via the ‘--funcall’ option).
変数after-init-timeに、current-timeの値をセットする。この変数は事前にnilにセットされている。これをカレント時刻にセットすることが、初期化フェーズが終わったことの合図となり、かつbefore-init-timeと共に用いることにより、初期化に要した時間の計測手段を提供する。
ノーマルフックafter-init-hookを実行する。
バッファー*scratch*が存在し、それがまだ(デフォルトであるべき)Fundamentalモードなら、initial-major-modeに応じたメジャーモードをセットする。
テキスト端末で開始された場合は、その端末固有のLispライブラリー(端末固有の初期化を参照)をロードして、フックtty-setup-hookを実行する。これは--batchモード、またはterm-file-prefixがnilなら実行されない。
inhibit-startup-echo-area-messageで抑制していなければ、エコーエリアに初期メッセージを表示する。
これ以前に処理されていない、すべてのコマンドラインオプションを処理する。
オプション--batchが指定されていたら、ここでexitする。
If the *scratch* buffer exists and is empty, it inserts (substitute-command-keys initial-scratch-message) into that buffer.
If initial-buffer-choice is a string, it visits the file (or directory) with that name. If it is a function, it calls the function with no arguments and selects the buffer that it returns. If one file is given as a command line argument, that file is visited and its buffer displayed alongside initial-buffer-choice. If more than one file is given, all of the files are visited and the *Buffer List* buffer is displayed alongside initial-buffer-choice.
emacs-startup-hookを実行する。
initファイルの指定が何であれ、それに応じて選択されたフレームのパラメーターを変更するframe-notice-user-settingsを呼び出す。
window-setup-hookを実行する。このフックとemacs-startup-hookの違いは、前述したフレームパラメーターの変更後にこれが実行される点だけである。
copyleftとEmacsの基本的な使い方を含む特別なバッファーである、スタートアップスクリーン(startup screen)ヲ表示する。これはinhibit-startup-screenかinitial-buffer-choiceが非nil、あるいはコマンドラインオプション‘--no-splash’か‘-Q’が指定されていたら行われない。
If a daemon was requested, it calls server-start. (On POSIX systems, if a background daemon was requested, it then detaches from the controlling terminal.) See Emacs Server in The GNU Emacs Manual.
セッションマネージャーにより開始された場合には、以前のセッションのIDを引数として、emacs-session-restoreを呼び出す。セッションマネージャーを参照のこと。

以下のオプションは、スタートアップシーケンスの側面のいくつかに影響を与えます。

User Option: inhibit-startup-screen

この変数が非nilなら、スタートアップスクリーンを抑制する。この場合、通常Emacsは*scratch*バッファーを表示する。しかし、以下のinitial-buffer-choiceを参照されたい。

新しいユーザーがcopyleftやEmacsの基本的な使い方に関する情報を入手するのを防げるので、新しいユーザーのinitファイル内や、複数のユーザーぶ影響するような方法でこの変数をセットしてはならない

inhibit-startup-messageとinhibit-splash-screenは、この変数にたいするエイリアスである。

User Option: initial-buffer-choice: 非nilなら、この変数はスタートアップ後にスタートアップスクリーンのかわりにEmacsが表示するファイルを指定する文字列であること。この変数が関数なら、Emacsはその関数を呼び出し、その関数はその後に表示するバッファーをリターンしなければならない。値がtなら、Emacsは*scratch*バッファーを表示する。

User Option: inhibit-startup-echo-area-message

この変数はエコーエリアのスタートアップメッセージの表示を制御する。ユーザーのinitファイル内に以下の形式のテキストを追加することにより、エコーエリアのスタートアップメッセージを抑制できる:

(setq inhibit-startup-echo-area-message
      "your-login-name")

Emacsはユーザーのinitファイル内の、上記のような式を明示的にチェックする。ユーザーのロフイン名は、Lispの文字列定数としてこの式内に記述されていなければならない。Customizeインターフェイスを使用することもできる。他の方法で同じ値にinhibit-startup-echo-area-messageをセットしても、スタートアップメッセージは抑制されない。この方法により、望むならユーザー自身で簡単にメッセージを抑制できるが、単に自分用のiniファイルを別のユーザーにコピーしても、メッセージは抑制されないだろう。

User Option: initial-scratch-message: This variable, if non-nil, should be a string, which is treated as documentation to be inserted into the *scratch* buffer when Emacs starts up. If it is nil, the *scratch* buffer is empty.

以下のコマンドラインオプションは、スタートアップシーケンスのいくつかの側面に影響を与えます。Initial Options in The GNU Emacs Manualを参照してください。

--no-splash: スプラッシュスクリーンを表示しない。
--batch: 対話的な端末なしで実行する。batchモードを参照のこと。
--daemon
--bg-daemon
--fg-daemon: Do not initialize any display; just start a server. (A “background” daemon automatically runs in the background.)
--no-init-file
-q: initファイルとdefaultライブラリーをいずれもロードしない。
--no-site-file: site-startライブラリーをロードしない。
--quick
-Q: ‘-q --no-site-file --no-splash’と等価。

40.1.2 initファイル

Emacsの開始時は通常、ユーザーのinitファイル(init file)のロードを試みます。これはユーザーのホームディレクトリー内にある.emacsまたは.emacs.elという名前のファイル、あるいはホームディレクトリーの.emacs.dという名前のサブディレクトリー内にあるinit.elという名前のファイルのいずれかのファイルです。

コマンドラインスイッチ‘-q’、‘-Q’、‘-u’はinitファイルを探すべきかと、どこで探すかを制御します。‘-u user’はそのユーザーではなくuserのinitファイルのロードを指示しますが、‘-q’(‘-Q’のほうが強力)はinitファイルをロードしないことを指示します。Entering Emacs in The GNU Emacs Manualを参照してください。いずれのオプションも指定されていなければ、ユーザーのホームディレクリーからinitファイルを探すために、Emacsは環境変数LOGNAME、USER(ほとんどのシステム)、またはUSERNAME(MSシステム)を使用します。この方法により、たとえsuしていたとしても、依然としてEmacsはそのユーザー自身のinitファイルをロードできるのです。これらの環境変数が存在していなくても、EmacsはユーザーIDからユーザーのホームディレクトリーを探します。

インストールしたEmacsによってはdefault.elというLispライブラリーの、デフォルトinitファイル(default init file)が存在するかもしれません。Emacsはライブラリーの標準検索パスからこのファイルを探します(プログラムがロードを行う方法を参照)。Emacsディストリビューションには、このファイルはローカルなカスタマイズを意図しています。デフォルトinitファイルが存在する場合は、常にこのファイルがEmacs開始時にロードされます。しかしユーザー自身のinitファイルが存在する場合には、それが最初にロードされます。それによりinhibit-default-initが非nil値にセットされた場合、Emacsは後続するdefault.elファイルのロードを行いません。batchモード、または‘-q’(または‘-Q’)を指定した場合、Emacsは個人的なinitファイルトでデフォルトinitファイのいずれもロードしません。

サイトのカスタマイズのためのファイルは、site-start.elです。Emacsはユーザーのinitファイルの前にこれをロードします。オプション‘--no-site-file’により、このファイルのロードを抑制できます。

User Option: site-run-file: この変数は、ユーザーのinitファイルの前にロードする、サイト用カスタマイズファイルを指定する。通常の値は"site-start"。実際に効果があるようにこれを変更するには、Emacsのdump前に変更するのが唯一の方法となる。

一般的に必要とされる.emacsファイルのカスタマイズ方法については、Init File Examples in The GNU Emacs Manualを参照のこと。

User Option: inhibit-default-init: この変数が非nilなら、Emacsがデフォルトの初期化ライブラリーファイルをロードするのを防ぐ。デフォルト値はnil。

Variable: before-init-hook: このノーマルフックは、すべてのinitファイル(site-start.el、ユーザーのinitファイル、およびdefault.el)のロード直前に一度実行される。(実際に効果があるようにこれを変更するには、Emacsのdump前に変更するのが唯一の方法となる。)

Variable: after-init-hook: このノーマルフックは、すべてのinitファイル(site-start.el、ユーザーのinitファイル、およびdefault.el)のロード直後、端末固有ライブラリーのロードとコマンドラインアクション引数の処理の前に一度実行される。

Variable: emacs-startup-hook: このノーマルフックは、コマンドライン引数の処理直後に一度実行される。batchモードでは、Emacsはこのフックを実行しない。

Variable: window-setup-hook: このノーマルフックは、emacs-startup-hookと非常に似ている。このフックが若干遅れて、フレームパラメーターのセット後に実行されるのが唯一の違いである。window-setup-hookを参照のこと。

Variable: user-init-file: この変数は、ユーザーのinitファイルの絶対ファイル名を保持する。実際にロードされたinitファイルが.emacs.elcのようなコンパイル済なら、値はそれに対応するソースファイルを参照する。

Variable: user-emacs-directory: この変数は、.emacs.dディレクトリーの名前を保持する。これは、MS-DOS以外のプラットフォームでは~/.emacs.dである。

40.1.3 端末固有の初期化

Each terminal type can have its own Lisp library that Emacs loads when run on that type of terminal. The library’s name is constructed by concatenating the value of the variable term-file-prefix and the terminal type (specified by the environment variable TERM). Normally, term-file-prefix has the value "term/"; changing this is not recommended. If there is an entry matching TERM in the term-file-aliases association list, Emacs uses the associated value in place of TERM. Emacs finds the file in the normal manner, by searching the load-path directories, and trying the ‘.elc’ and ‘.el’ suffixes.

端末固有ライブラリーの通常の役割は、特殊キーによりEmacsが認識可能なシーケンスを送信可能にすることです。TermcapとTerminfoのエントリーがその端末のすべてのファンクションキーを指定していなければ、input-decode-mapへのセットや追加も必要になるかもしれません。端末の入力を参照してください。

端末タイプにハイフンとアンダースコアーが含まれ、その端末名に等しい名前のライブラリーが見つからないときには、Emacsはその端末名から最後のハイフンまたはアンダースコアー以降を取り除いて再試行します。このプロセスはEmacsがマッチするライブラリーを見つかるか、その名前にハイフンとアンダースコアーが含まれなくなる(つまりその端末固有ファイルが存在しない)まで繰り返されます。たとえば端末名が‘xterm-256color’でterm/xterm-256color.elというライブラリーが存在しない場合、Emacsはterm/xterm.elのロードを試みます。必要なら、その端末タイプの完全な名称を見つかるために、端末ライブラリーは(getenv "TERM")を評価することができます。

initファイルで変数term-file-prefixをnilにセットすることにより、端末固有ライブラリーのロードを防ぐことができます。

tty-setup-hookを使用することにより、端末固有ライブラリーのいくつかのアクションのアレンジやオーバーライドもできます。これは新たなテキスト端末の初期化語にEmacsが実行するノーマルフックです。自身のライブラリーをもたない端末にたいする初期化を定義するために、このフックを使用することのできるでしょう。フックを参照してください。

User Option: term-file-prefix

この変数の値が非nilなら、Emacsは以下のように端末固有初期化ファイルをロードする:

(load (concat term-file-prefix (getenv "TERM")))

端末初期化ファイルのロードを望まない場合には、変数term-file-prefixにnilをセットできる。

MS-DOSでは、Emacsは環境変数TERMに‘internal’をセットする。

User Option: term-file-aliases: This variable is an association list mapping terminal types to their aliases. For example, an element of the form ("vt102" . "vt100") means to treat a terminal of type ‘vt102’ like one of type ‘vt100’.

Variable: tty-setup-hook

この変数は、新たなテキスト端末の初期化後にEmacsが実行するノーマルフックである。(これは非ウィンドウのモードでのEmacs開始時とemacsclientのTTY接続作成時に適用される。) (適用可能なら)このフックはユーザーのinitファイル、および端末固有Lispファイルのロード後に実行されるので、そのファイルにより行われた定義を調整するために、このフックを使用できる。

関連する機能については、window-setup-hookを参照のこと。

40.1.4 コマンドライン引数

Emacs開始時に種々のアクションをリクエストするために、コマンドライン引数を使用できます。Emacsを使う際は、ログイン後に一度だけ起動して、同一のEmacsセッション内ですべてを行うのが推奨される方法です(Entering Emacs in The GNU Emacs Manualを参照)。この理由により、コマンドライン引数を頻繁に使うことはないかもしれません。それでもセッションスクリプトからEmacsを呼び出すときやEmacsのデバッグ時に、コマンドライン引数が有用になるかもしれません。このセクションでは、Emacsがコマンドライン引数を処理する方法を説明します。

Function: command-line: この関数は、Emacsが呼び出された際のコマンドライン引数を解析、処理、そして(とりわけ)ユーザーのinitファイルをロードして、スタートアップメッセージを表示する。

Variable: command-line-processed

この変数の値は、一度コマンドラインが処理されるとtになる。

dump-emacs(Emacsのビルドを参照)を呼び出すことによりEmacsを再dumpする場合は、新たにdumpされたEmacsに新たなコマンドライン引数を処理させるために、最初にこの変数にnilをセットしたいと思うかもしれない。

Variable: command-switch-alist

この変数は、ユーザー定義のコマンドライン引数とそれに関連付けられたハンドラー関数のalistである。デフォルトは空だが、望むなら要素を追加できる。

コマンドラインオプション(command-line option)ハ、以下の形式をもつコマンドライン上の引数である:

-option

command-switch-alistの要素は以下のようになる:

(option . handler-function)

CARのoptionは文字列で、コマンドラインオプションの名前である(先頭のハイフンは含まない)。handler-functionはoptionを処理するために呼び出され、単一の引数としてオプション名を受け取る。

このオプションは、コマンドライン内で引数を併う場合がある。この場合、handler-functionは残りのコマンドライン引数すべてを、変数command-line-args-left(以下参照)で見い出すことができる(コマンドライン引数のリスト全体はcommand-line-args)。

コマンドライン引数は、startup.elファイル内のcommand-line-1により解析される。Command Line Arguments for Emacs Invocation in The GNU Emacs Manualも参照されたい。

Variable: command-line-args: この変数の値は、Emacsに渡されたコマンドライン引数のリストである。

Variable: command-line-args-left: この変数の値は、まだ処理されていないコマンドライン引数のリストである。

Variable: command-line-functions

この変数の値は、認識されなかったコマンドライン引数を処理するための関数のリストである。次の引数が処理されてそれに特別な意味がないときは毎回、このリスト内の関数が非nilをリターンするまでリスト内の出現順に呼び出される。

これらの関数は引数なしで呼び出される。関数は、その時点で一時的にバインドされている変数argiを通じて、検討中のコマンドラインにアクセスできる。残りの引数(カレントの引数含まず)は、変数command-line-args-left内にあえう。

関数がargi内のその引数を認識して処理したときは、その引数を処理したと告げるために非nilをリターンすること。後続の引数のいくつかを処理したときは、command-line-args-leftからそれらを削除してそれを示すことができる。

これらの関数すべてがnilをリターンした場合、その引数はvisitすべきファイル名として扱われる。

40.2 Emacsからの脱出

Emacsから抜け出すには2つの方法があります: 1つ目は永遠にexitするEmacsジョブのkillであり、2つ目はサスペンドする方法で、これは後からEmacsプロセスに再エンターすることができます。(もちろんグラフィカルな環境では、Emacsで特に何もせず単に他のアプリケーションにスイッチして、後で望むときにEmacsに戻れる。)

40.2.1 Emacsのkill

Emacsのkillとは、Emacsプロセスの終了を意味します。端末からEmacsを開始した場合、通常は親プロセスの制御が再開されます。Emacsをkillする低レベルなプリミティブはs kill-emacsです。

Command: kill-emacs &optional exit-data

このコマンドはフックkill-emacs-hookを呼び出してから、Emacsプロセスをexitしてそれをkillする。

exit-dataが整数なら、それはEmacsプロセスのexitステータスとして使用される。(これは主にbatch処理で有用。batchモードを参照されたい。)

exit-dataが文字列なら、その内容は端末の入力バッファーに詰め込まれるので、shell(または何であれ次の入力を読み込むプログラム)が読み込むことができる。

関数kill-emacsは通常、より高位なレベルコマンドC-x C-c (save-buffers-kill-terminal)を通じて呼び出される。Exiting in The GNU Emacs Manualを参照のこと。これはEmacsがオペレーティングシステムのシグナルSIGTERMがSIGHUPを受け取った場合(たとえば制御端末が切断されたとき)や、batchモードで実行中にSIGINTを受け取った場合(batchモードを参照)にも、自動的にこれが呼び出される。

Variable: kill-emacs-hook

このノーマルフックは、Emacsのkillの前にkill-emacsにより実行される。

kill-emacsは、ユーザーとの対話が不可能な状況(たとえば端末が切断されたとき)で呼び出されるかもしれないので、このフックの関数はユーザーとの対話を試みるべきではない。Emacsシャットダウン時にユーザーと対話したければ、下記のkill-emacs-query-functionsを使用すること。

Emacsをkillしたときには保存されたファイルを除き、Emacsプロセス内のすべての情報が失われます。うっかりEmacsをkillすることで大量の作業が失われるので、save-buffers-kill-terminalコマンドは保存を要するバッファーがあったり実行中のサブプロセスがある場合には確認の問い合わせを行います。これはアブノーマルフックkill-emacs-query-functionsも実行します。

User Option: kill-emacs-query-functions: save-buffers-kill-terminalがEmacsをkillする際には、標準の質問を尋ねた後、kill-emacsを呼び出す前にこのフック内の関数を呼び出す。関数は出現順に引数なしで呼び出される。関数はそれぞれ、追加ユーザーから確認を求めることができる。それらのいずれかがnilをリターンすると、save-buffers-kill-emacsはEmacsをkillせず、このフック内の残りの関数は実行されない。直接kill-emacsを呼び出すと、このフックは実行されない。

40.2.2 Emacsのサスペンド

テキスト端末では、Emacsのサスペンドができます。これはEmacsを一時的にストップして上位のプロセスに制御を返します。これは通常はshellになります。これにより後で同じEmacsプロセス内の、同じバッファー、同じkillリング、同じアンドゥヒストリー、...で編集を再開できます。Emacsを再開するには、親shell内で適切なコマンド — 恐らくはfg — を使用します。

そのEmacsセッションが開始された端末デバイス上でのみサスペンドは機能します。そのデバイスのことを、そのセッションの制御端末(controlling terminal)と呼びます。制御端末がグラフィカルな端末の場合、サスペンドは許されません。グラフィカルな端末では、Emacsで特別なことをせずに単に別のアプリケーションにスイッチできるので、サスペンドは通常は関係ありません。

Some operating systems (those without SIGTSTP, or MS-DOS) do not support suspension of jobs; on these systems, suspension actually creates a new shell temporarily as a subprocess of Emacs. Then you would exit the shell to return to Emacs.

Command: suspend-emacs &optional string

この関数はEmacsを停止して、上位のプロセスに制御を返す。上位プロセスがEmacsを再開するとその際には、Lispでのsuspend-emacsの呼び出し元にnilをリターンする。

この関数は、そのEmacsセッションの制御端末上でのみ機能する。他のTTYデバイスの制御を放棄するには、suspend-ttyを使用する(下記参照)。そのEmacsセッションが複数の端末を使用する場合には、Emacsのサスペンド前に他のすべての端末からフレームを削除しなければならず、さもないとこの関数はエラーをシグナルする。複数の端末を参照のこと。

stringが非nilなら、その各文字はEmacsの上位shellに端末入力として送信される。string内の文字は上位shellによりエコーされずに、結果だけが表示される。

サスペンドする前に、suspend-emacsはノーマルフックsuspend-hookを実行する。ユーザーがEmacs再開後に、suspend-emacsはノーマルフックsuspend-resume-hookを実行する。フックを参照のこと。

再開後の次回再表示では、変数no-redraw-on-reenterがnilならスクリーン全体が再描画される。スクリーンのリフレッシュを参照のこと。

以下はこれらのフックの使用例である:

(add-hook 'suspend-hook
          (lambda () (or (y-or-n-p "Really suspend? ")
                         (error "Suspend canceled"))))

(add-hook 'suspend-resume-hook (lambda () (message "Resumed!")
                                 (sit-for 2)))

(suspend-emacs "pwd")を評価すると以下を目にするだろう:

---------- Buffer: Minibuffer ----------
Really suspend? y
---------- Buffer: Minibuffer ----------

---------- Parent Shell ----------
bash$ /home/username
bash$ fg

---------- Echo Area ----------
Resumed!

Emacsサスペンド後に‘pwd’がエコーされないことに注意。エコーはされないが、shellにより読み取られ実行されている。

Variable: suspend-hook: この変数は、Emacsがサスペンド前に実行するノーマルフックである。

Variable: suspend-resume-hook: この変数は、サスペンド後の再開時にEmacsが実行するノーマルフックである。

Function: suspend-tty &optional tty

ttyにEmacsが使用する端末デバイスを指定すると、この関数はそのデバイスを放棄して、それを以前の状態にリストアする。そのデバイスを使用していたフレームは存在を続けるが更新はされず、Emacsはそれらのフレームから入力を読み取らない。ttyには端末オブジェクト、フレーム(そのフレームの端末の意)、nil(選択されたフレームの端末の意)を指定できる。複数の端末を参照のこと。

ttyがサスペンド済みなら、この関数は何も行わない。

この関数は、端末オブジェクトを各関数への引数として、フックsuspend-tty-functionsを実行する。

Function: resume-tty &optional tty

この関数は、以前にサスペンドされたデバイスttyを再開する。ここでttyは、suspend-ttyに指定できるのと同じである。

この関数は端末デバイスの再オープンと再初期化を行い、その端末の選択されたフレームで端末を再描画する。それから端末ブジェクトを各関数への引数として、フックresume-tty-functionsを実行する。

同じデバイスが別のEmacs端末で使用済みなら、この関数はエラーをシグナルする。ttyがサスペンドされていなければ、この関数は何もしない。

Function: controlling-tty-p &optional tty: この関数は、ttyがそのEmacsセッションの制御端末なら、非nilをリターンする。ttyには端末オブジェクト、フレーム(そのフレームの端末の意)、nil(選択されたフレームの端末の意)を指定できる。

Command: suspend-frame: このコマンドはフレームをサスペンドする。GUIフレームではiconify-frameを呼び出す(フレームの可視性を参照)。テキスト端末上のフレームでは、そのフレームが制御端末デバイス上で表示されていればsuspend-emacs、されていなければsuspend-ttyのいずれかを呼び出す。

40.3 オペレーティングシステムの環境

Emacsはさまざまな変数を通じて、オペレーティングシステム環境内の変数へのアクセスを提供します。これらの変数には、システムの名前、ユーザーのUIDなどが含まれます。

Variable: system-configuration: この変数は、ユーザーのシステムのハードウェアとソフトウェアにたいするGNUの標準コンフィグレーション名(standard GNU configuration name)を保持する。たとえば64ビットGNU/Linuxシステムにたいする典型的な値は‘"x86_64-unknown-linux-gnu"’である。

Variable: system-type

この変数の値は、Emacs実行中のオペレーティングシステムのタイプを示すシンボルである。可能な値は：

aix: IBMのAIX。
berkeley-unix: Berkeley BSDとその変種。
cygwin: Cygwin, a POSIX layer on top of MS-Windows.
darwin: Darwin (macOS).
gnu: (HURDとMachから構成される)GNUシステム。
gnu/linux: GNU/Linuxシステム — すなわちLinuxカーネルを使用するGNUシステムの変種。(これらのシステムは人がしばしば“Linux”と呼ぶシステムだが、実際にはLinuxは単なるカーネルであり、システム全体ではない。)
gnu/kfreebsd: FreeBSDカーネルによる(glibcベースの)GNUシステム。
hpux: ヒューレット・パッカードのHPUXオペレーティングシステム。
nacl: Google Native Client (NaCl) sandboxing system.
ms-dos: MicrosoftのDOS。MS-DOSにたいするDJGPPでコンパイルされたEmacsは、たとえMS-Windows上で実行されていてもsystem-typeがms-dosにバインドされる。
usg-unix-v: AT&TのUnix System V。
windows-nt: Microsoft Windows NT, 9X and later. The value of system-type is always windows-nt, e.g., even on Windows 10.

わたしたちは絶対に必要になるまでは、より細分化するために新たなシンボルを追加したくありません。実際のところ、将来的にはこれらの候補のいくつかを取り除きたいと思っています。system-typeで許されているより細分化する必要がある場合には、たとえば正規表現にたいしてsystem-configurationをテストできます。

Function: system-name: この関数は、実行中のマシン名を文字列としてリターンする。

User Option: mail-host-address: If this variable is non-nil, it is used instead of system-name for purposes of generating email addresses. For example, it is used when constructing the default value of user-mail-address. See section ユーザーの識別.

Command: getenv var &optional frame

この関数は、環境変数varの値を文字列としてリターンする。varは文字列であること。その環境内でvarが未定義なら、getenvはnilをリターンする。varがセットされているがnull(訳注: 空文字列)なら、‘""’をリターンする。Emacs内では、環境変数とそれらの値のリストは、変数process-environment内に保持されている。

(getenv "USER")
     ⇒ "lewis"

shellコマンドprintenvは環境変数すべて、または一部をプリントする:

bash$ printenv
PATH=/usr/local/bin:/usr/bin:/bin
USER=lewis

TERM=xterm
SHELL=/bin/bash
HOME=/home/lewis

…

Command: setenv variable &optional value substitute

このコマンドは、variableという名前の環境変数の値に、valueをセットする。variableは文字列であること。内部的には、Emacs Lispは任意の文字列を扱える。しかし通常variableはshell識別子として有効、すなわちアルファベットかアンダースコアで始まる、アルファベット、数字またはアンダースコアのシーケンスであること。それ以外の場合、Emacsのサブプロセスがvariableの値にアクセスを試みるとエラーが発生するかもしれない。valueが省略またはnilの場合(またはプレフィクス引数とともにインタラクティブに呼び出された場合)、setenvはその環境からvariableを削除する。それ以外の場合、variableは文字列であること。

オプション引数substituteが非nilなら、value内のすべての環境変数を展開するために、Emacsは関数substitute-env-varsを呼び出す。

setenvはprocess-environmentを変更することにより機能する。この変数をletでバインドするのも、合理的プラクティスである。

setenvはvariableの新たな値、または環境からvariableが削除されていればnilをリターンする。

Variable: process-environment

この変数は、それぞれが1つの環境変数を記す文字列リストである。関数getenvとsetenvは、この変数により機能する。

process-environment
⇒ ("PATH=/usr/local/bin:/usr/bin:/bin"
    "USER=lewis"

    "TERM=xterm"
    "SHELL=/bin/bash"
    "HOME=/home/lewis"
    …)

If process-environment contains multiple elements that specify the same environment variable, the first of these elements specifies the variable, and the others are ignored.

Variable: initial-environment: この変数は、Emacs開始時にその親プロセスからEmacsが継承した環境変数のリストを保持する。

Variable: path-separator: この変数は、(環境変数で見つけた)検索パス内でディレクトリーを区切る文字を示す文字列を保持する。値はUnixとGNUシステムでは":"、MSシステムでは";"である。

Function: parse-colon-path path

This function takes a search path string such as the value of the PATH environment variable, and splits it at the separators, returning a list of directories. nil in this list means the current directory. Although the function’s name says “colon”, it actually uses the value of path-separator.

(parse-colon-path ":/foo:/bar")
     ⇒ (nil "/foo/" "/bar/")

Variable: invocation-name: この変数は、Emacsが呼び出された時のプログラム名を保持する。値は文字列で、ディレクトリー名は含まれない。

Variable: invocation-directory: This variable holds the directory in which the Emacs executable was located when it was run, or nil if that directory cannot be determined.

Variable: installation-directory: 非nilなら、それはサブディレクトリーlib-srcとetcを探すディレクトリーである。インストールされたEmacsなら、通常はnil。Emacsが標準のインストール位置にそれらのディレクトリーを見つけられないものの、Emacs実行可能形式を含むディレクトリー(たとえばinvocation-directory)に何らかの関連があるディレクトリーで見つかることができたら非nilならとなる。

Function: load-average &optional use-float

この関数は現在、1分、5分、15分のロードアベレージ(load averages: 平均負荷)をリストでリターンする。このロードアベレージは、そのシステム上で実行を試みているプロセス数を示す。

デフォルトでは、この値はシステムロードアベレージを100倍にした整数だが、use-floatが非nilなら100を乗ずることなくこれらの値は浮動小数点数としてリターンされる。

ロードアベレージ入手が不可能なら、この関数はエラーをシグナルする。いくつかのプラットフォームでは、ロードアベレージへのアクセスにカーネル情報を読み取れるよう、通常は推奨されないsetuidかsetgidしたEmacsのインストールを要する。

1分のロードアベレージは利用できるが、5分と15分のアレージは利用できない場合、この関数は利用可能なアベレージを含んだ短縮されたリストをリターンする。

(load-average)
     ⇒ (169 48 36)

(load-average t)
     ⇒ (1.69 0.48 0.36)

shellコマンドのuptimeは、これと類似した情報をリターンする。

Function: emacs-pid: この関数は、EmacsプロセスのプロセスIDを整数としてリターンする。

Variable: tty-erase-char: この変数は、Emacs開始前にそのシステムの端末ドライバーで選択されていた、erase文字を保持する。

40.4 ユーザーの識別

Variable: init-file-user

この変数は、Emacsによりどのユーザーのinitが使用されるべきかを — なければnilをリターンする。""は、ログイン時のオリジナルのユーザーをリターンする。この値は‘-q’や‘-u user’のような、コマンドラインオプションを反映する。

カスタマイズ関連のファイルや、他の類の短いユーザープロファイルをロードするLispパッケージは、それをどこで探すか判断するために、この変数にしたがうべきである。これらのLispパッケージは、この変数内で見つかったユーザー名のプロファイルをロードすること。init-file-userがnilなら‘-q’、‘-Q’、または‘-batch’オプションが使用されたことを意味し、その場合Lispパッケージはカスタマイズファイルやユーザープロファイルを何もロードするべきではない。

User Option: user-mail-address: This holds the email address of the user who is using Emacs.

Function: user-login-name &optional uid

この関数は、そのユーザーのログイン名をリターンする。これはいずれかがセットされていれば、環境変数LOGNAMEかUSERを使用する。それ以外なら、この値は実UIDではなく実効UIDにもとづく。

uid(数字)を指定した場合、uidに対応するユーザー名、そのようなユーザーが存在しなければnilが結果となる。

Function: user-real-login-name: この関数は、Emacsの実UIDに対応するユーザー名をリターンする。これは実効UID、および環境変数LOGNAMEとUSERを無視する。

Function: user-full-name &optional uid

この関数はログインユーザーの完全名、環境変数NAMEがセットされていればその値をリターンする。

EmacsプロセスのユーザーIDが既知のユーザーに不一致(かつ与えられたNAMEが未セット)なら、結果は"unknown"となる。

uidが非nilなら、それは数字(ユーザーID)か文字列(ログイン名)であること。その場合、user-full-nameはそのユーザー名かログイン名に対応する完全名をリターンする。未定義のユーザー名かログイン名を指定すると、nilをリターンする。

The symbols user-login-name, user-real-login-name and user-full-name are variables as well as functions. The functions return the same values that the variables hold. These variables allow you to fake out Emacs by telling the functions what to return. The variables are also useful for constructing frame titles (see section フレームのタイトル).

Function: user-real-uid: この関数は、そのユーザーの実UIDをリターンする。この値は、(非現実的だが)そのUIDがLisp整数の範囲を超える程大きいような場合には、浮動小数点数になるかもしれない。

Function: user-uid: この関数は、そのユーザーの実効UIDをリターンする。値は浮動小数点数かもしれない。

Function: group-gid: この関数は、そのユーザーの実効GIDをリターンする。値は浮動小数点数かもしれない。

Function: group-real-gid: この関数は、そのユーザーの実GIDをリターンする。値は浮動小数点数かもしれない。

Function: system-users: この関数は、そのシステム上のユーザー名をリストする、文字列のリストをリターンする。この情報をEmacsが取得できなければ、user-real-login-nameの値のみを含むリストをリターンする。

Function: system-groups: この関数は、そのシステム上のグループ名をリストする、文字列のリストをリターンする。この情報をEmacsが取得できなければ、リターン値はnil。

40.5 時刻

このセクションでは、カレント時刻とタイムゾーンを決定する方法を説明します。

Most of these functions represent time as a list of four integers (sec-high sec-low microsec picosec). This represents the number of seconds from the epoch (January 1, 1970 at 00:00 UTC), using the formula: high * 2**16 + low + micro * 10**-6 + pico * 10**-12. The return value of current-time represents time using this form, as do the timestamps in the return values of other functions such as file-attributes (see Definition of file-attributes). In some cases, functions may return two- or three-element lists, with omitted microsec and picosec components defaulting to zero.

Function arguments, e.g., the time argument to current-time-string, accept a more-general time value format, which can be a list of integers as above, or a single number for seconds since the epoch, or nil for the current time. You can convert a time value into a human-readable string using current-time-string and format-time-string, into a list of integers using seconds-to-time, and into other forms using decode-time and float-time. These functions are described in the following sections.

Function: current-time-string &optional time zone

この関数は、カレントの時刻と日付を可読形式の文字列でリターンする。この文字列の先頭部分には曜日、月、日付、時刻がこの順に含まれ、それらが可変長となることはない。これらのフィールドにたいして使用される文字数は常に同じなので、それらを切り出すために安心してsubstringを使用できる。年の部分は正確に4桁とは限らず、いつか追加情報が終端に不可されるかもしれないので、文字列終端からではなく先頭から文字を数えること。

The argument time, if given, specifies a time to format, instead of the current time. The optional argument zone defaults to the current time zone rule. See section Time Zone Rules.

(current-time-string)
     ⇒ "Wed Oct 14 22:21:05 1987"

Function: current-time: この関数は4つの整数のリスト(sec-high sec-low microsec picosec)で表されたカレント時刻をリターンする。これらの整数うち後部は、低精度の時刻をリターンするシステムでは0になる。現在のすべてのマシンでは、picosecは1000の倍数だが、より高精度のクロックが利用可能になったら変更されるかもしれない。

Function: float-time &optional time

This function returns the current time as a floating-point number of seconds since the epoch. The optional argument time, if given, specifies a time to convert instead of the current time.

警告: 結果は浮動小数点数なので、正確ではないかもしれない。正確なタイムスタンプが必要なら、この関数を使用しないこと。

time-to-seconds is an alias for this function.

Function: seconds-to-time time: This function converts a time value to list-of-integer form. For example, if time is a number, (time-to-seconds (seconds-to-time time)) equals the number unless overflow or rounding errors occur.

40.6 Time Zone Rules

The default time zone is determined by the TZ environment variable. See section オペレーティングシステムの環境. For example, you can tell Emacs to default to Universal Time with (setenv "TZ" "UTC0"). If TZ is not in the environment, Emacs uses system wall clock time, which is a platform-dependent default time zone.

The set of supported TZ strings is system-dependent. GNU and many other systems support the tzdata database, e.g., ‘"America/New_York"’ specifies the time zone and daylight saving time history for locations near New York City. GNU and most other systems support POSIX-style TZ strings, e.g., ‘"EST+5EDT,M4.1.0/2,M10.5.0/2"’ specifies the rules used in New York from 1987 through 2006. All systems support the string ‘"UTC0"’ meaning Universal Time.

Functions that convert to and from local time accept an optional time zone rule argument, which specifies the conversion’s time zone and daylight saving time history. If the time zone rule is omitted or nil, the conversion uses Emacs’s default time zone. If it is t, the conversion uses Universal Time. If it is wall, the conversion uses the system wall clock time. If it is a string, the conversion uses the time zone rule equivalent to setting TZ to that string. If it is a list (offset abbr), where offset is an integer number of seconds east of Universal Time and abbr is a string, the conversion uses a fixed time zone with the given offset and abbreviation. An integer offset is treated as if it were (offset abbr), where abbr is a numeric abbreviation on POSIX-compatible platforms and is unspecified on MS-Windows.

Function: current-time-zone &optional time zone

この関数は、そのユーザーが居るタイムゾーンを記すリストをリターンする。

The value has the form (offset abbr). Here offset is an integer giving the number of seconds ahead of Universal Time (east of Greenwich). A negative value means west of Greenwich. The second element, abbr, is a string giving an abbreviation for the time zone, e.g., ‘"CST"’ for China Standard Time or for U.S. Central Standard Time. Both elements can change when daylight saving time begins or ends; if the user has specified a time zone that does not use a seasonal time adjustment, then the value is constant through time.

この値を計算するのに必要なすべての情報をオペレーティングシステムが提供しない場合、このリストの未知の要素はnilになる。

The argument time, if given, specifies a time value to analyze instead of the current time. The optional argument zone defaults to the current time zone rule.

40.7 時刻の変換

These functions convert time values (see section 時刻) into calendrical information and vice versa.

Many 32-bit operating systems are limited to system times containing 32 bits of information in their seconds component; these systems typically handle only the times from 1901-12-13 20:45:52 through 2038-01-19 03:14:07 Universal Time. However, 64-bit and some 32-bit operating systems have larger seconds components, and can represent times far in the past or future.

時刻変換関数は、たとえグレゴリオ暦導入前の日付にたいしても、常にグレゴリオ暦を使用します。年はB.C. 1年から年数を数え、伝統的なグレゴリオ年が行うように0年をスキップしません。たとえば年数-37は、グレゴリオ年のB.C. 38年を表します。

Function: decode-time &optional time zone

This function converts a time value into calendrical information. If you don’t specify time, it decodes the current time, and similarly zone defaults to the current time zone rule. See section Time Zone Rules. The return value is a list of nine elements, as follows:

(seconds minutes hour day month year dow dst utcoff)

以下に各要素の意味を示す:

seconds: 0から59までの整数で表した分を過ぎた時分秒の秒。いくつかのオペレーティングシステムでは、閏秒にたいして60となる。
minutes: 0から59までの整数で表した、時を過ぎた時分秒の分。
hour: 0から23までの整数で表した時分秒の時。
day: 1から31までの整数で表した、年月日の日。
month: 1から12までの整数で表した、年月日の月。
year: 通常は1900より大きい整数で表した、年月日の年。
dow: 0から6までの整数で表した曜日で、0は日曜日を意味する。
dst: 夏時間が有効ならt、それ以外はnil。
utcoff: An integer indicating the Universal Time offset in seconds, i.e., the number of seconds east of Greenwich.

Common Lisp Note: Common Lisp has different meanings for dow and utcoff.

Function: encode-time seconds minutes hour day month year &optional zone

This function is the inverse of decode-time. It converts seven items of calendrical data into a list-of-integer time value. For the meanings of the arguments, see the table above under decode-time.

100未満の年が特別に扱われることはない。これを1900または2000を超える年を意味させたい場合は、encode-timeを呼び出す前に自身でこれらを修正しなければならない。

The optional argument zone defaults to the current time zone rule. See section Time Zone Rules.

encode-timeにたいして7個より多い引数を渡した、最初の6つはsecondsからyear、最後の引数がzoneとして使用され、その間の引数は無視される。これにより、以下のようにdecode-timeがリターンしたリストの要素を、encode-timeの引数として使用することが可能になる:

(apply 'encode-time (decode-time …))

seconds、minutes、hour、day、monthの引数に範囲外の値を使用することにより、単純な日付計算ができます。たとえばdayが0なら、それは与えられたmonthの前月末になります。

オペレーティングシステムは、可能なtime値の範囲に制限を設けます。範囲外の時刻のエンコードを試みると、結果はエラーとなります。たとえばあるシステムでは1970年以前では機能せず、別のシステムではより以前の1901年以降から機能します。

40.8 時刻のパースとフォーマット

These functions convert time values to text in a string, and vice versa. Time values include nil, numbers, and lists of two to four integers (see section 時刻).

Function: date-to-time string: この関数はtime文字列stringをパースして、それに対応するtime値をリターンする。

Function: format-time-string format-string &optional time zone

This function converts time (or the current time, if time is omitted or nil) to a string according to format-string. The conversion uses the time zone rule zone, which defaults to the current time zone rule. See section Time Zone Rules. The argument format-string may contain ‘%’-sequences which say to substitute parts of the time. Here is a table of what the ‘%’-sequences mean:

‘%a’: これは曜日の短縮名を意味する。
‘%A’: これは曜日の完全名を意味する。
‘%b’: これは月の短縮名を意味する。
‘%B’: これは月の完全名を意味する。
‘%c’: これは‘%x %X’のシノニムである。
‘%C’: This stands for the century, that is, the year divided by 100, truncated toward zero. The default field width is 2.
‘%d’: これは0パディングされた年月日の日である。
‘%D’: これは‘%m/%d/%y’のシノニムである。
‘%e’: これはブランクでパディングされた年月日の日である。
‘%F’: This stands for the ISO 8601 date format, i.e., ‘"%Y-%m-%d"’.
‘%g’: This stands for the year corresponding to the ISO week within the century.
‘%G’: This stands for the year corresponding to the ISO week.
‘%h’: これは‘%b’のシノニムである。
‘%H’: 時分秒の時(00から23)を意味する。
‘%I’: 時分秒の時(01から12)を意味する。
‘%j’: これは年内の経過日(001から366)を意味する。
‘%k’: これはブランクでパディングされた時分秒の時(0から23)を意味する。
‘%l’: これはブランクでパディングされた時分秒の時(1から12)を意味する。
‘%m’: これは年月日の月(01から12)を意味する。
‘%M’: これは時分秒の分(00から59)を意味する。
‘%n’: これは改行を意味する。
‘%N’: これはナノ秒(000000000–999999999)を意味する。うり少ない桁数を求める場合、ミリ秒は‘%3N’、マイクロ秒は‘%6N’を使用する。余分な桁は丸めずに切り捨てられる。
‘%p’: これは必要に応じて‘AM’か‘PM’を意味する。
‘%q’: This stands for the calendar quarter (1–4).
‘%r’: これは‘%I:%M:%S %p’のシノニムである。
‘%R’: これは‘%H:%M’のシノニムである。
‘%s’: This stands for the integer number of seconds since the epoch.
‘%S’: This stands for the second (00–59, or 00–60 on platforms that support leap seconds).
‘%t’: これはタブ文字を意味する。
‘%T’: これは‘%H:%M:%S’のシノニムである。
‘%u’: This stands for the numeric day of week (1–7). Monday is day 1.
‘%U’: これは週の開始を日曜日とみなした、年内の週(01から52)である。
‘%V’: This stands for the week of the year according to ISO 8601.
‘%w’: これは数字で表した曜日(0から6)で、日曜日が0。
‘%W’: これは週の開始を月曜日とみなした、年内の週(01から52)である。
‘%x’: これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では、これは‘%D’と等価である。
‘%X’: これはlocale固有の意味をもつ。デフォルトlocale(Cという名前のlocale)では、これは‘%T’と等価である。
‘%y’: これは世紀を含まない年(00から99)を意味する。
‘%Y’: これは世紀を併なう年を意味する。
‘%Z’: これはタイムゾーンの短縮形(たとえば‘EST’)を意味する。
‘%z’: This stands for the time zone numerical offset. The ‘z’ can be preceded by one, two, or three colons; if plain ‘%z’ stands for ‘-0500’, then ‘%:z’ stands for ‘-05:00’, ‘%::z’ stands for ‘-05:00:00’, and ‘%:::z’ is like ‘%::z’ except it suppresses trailing instances of ‘:00’ so it stands for ‘-05’ in the same example.
‘%%’: This stands for a single ‘%’.

One or more flag characters can appear immediately after the ‘%’. ‘0’ pads with zeros, ‘_’ pads with blanks, ‘-’ suppresses padding, ‘^’ upper-cases letters, and ‘#’ reverses the case of letters.

You can also specify the field width and type of padding for any of these ‘%’-sequences. This works as in printf: you write the field width as digits in a ‘%’-sequence, after any flags. For example, ‘%S’ specifies the number of seconds since the minute; ‘%03S’ means to pad this with zeros to 3 positions, ‘%_3S’ to pad with spaces to 3 positions. Plain ‘%3S’ pads with zeros, because that is how ‘%S’ normally pads to two positions.

The characters ‘E’ and ‘O’ act as modifiers when used after any flags and field widths in a ‘%’-sequence. ‘E’ specifies using the current locale’s alternative version of the date and time. In a Japanese locale, for example, %Ex might yield a date format based on the Japanese Emperors’ reigns. ‘E’ is allowed in ‘%Ec’, ‘%EC’, ‘%Ex’, ‘%EX’, ‘%Ey’, and ‘%EY’.

‘O’ means to use the current locale’s alternative representation of numbers, instead of the ordinary decimal digits. This is allowed with most letters, all the ones that output numbers.

To help debug programs, unrecognized ‘%’-sequences stand for themselves and are output as-is. Programs should not rely on this behavior, as future versions of Emacs may recognize new ‘%’-sequences as extensions.

この関数は、処理のほとんどを行うために、Cライブラリー関数strftimeを使用している(Formatting Calendar Time in The GNU C Library Reference Manualを参照)。その関数とやり取りするために、locale-coding-system(localeを参照)で指定されたコーディングシステムを使用して、引数のエンコーディングを最初に行う。strftimeが結果文字列をリターンした後に、その同じコーディングシステムを使用して、format-time-stringはデコードを行う。

Function: format-seconds format-string seconds

この関数は引数secondsを、format-stringに応じた年、日、時、...の文字列に変換する。引数format-stringには、その変換を制御する‘%’シーケンスを指定することができる。以下は‘%’が何を意味するかのテーブルである:

‘%y’
‘%Y’: 年間365日での年の整数。
‘%d’
‘%D’: 年月日の日。
‘%h’
‘%H’: 時分秒の時の整数。
‘%m’
‘%M’: 時分秒の分の整数。
‘%s’
‘%S’: 時分秒の秒の整数。
‘%z’: 非プリント制御フラグ。これを使用する際には、他の指定はサイズ減少順、すなわち年、日、時刻、分、...のように与えなければならない。最初の非0変換に遭遇するまで、‘%z’の左側の結果文字列は生成されない。たとえばemacs-uptime(emacs-uptimeを参照)で使用されるデフォルトフォーマットでは、秒数は常に生成されるが年、日、時、分はそれらが非0の場合のみ生成されるだろう。
‘%%’: リテラルの‘%’を生成する。

大文字のフォーマットシーケンスは数字に加えて単位を生成するが、小文字フォーマットは数字だけを生成する。

‘%’に続けてフィールド幅を指定できる。指定したフ幅より短ければ、ブランクでパディングされる。この幅の前にオプションでピリオドを指定すると、かわりに0パディングを要求する。たとえば"%.3Y"は、"004 years"を生成するだろう。

警告: この関数はmost-positive-fixnumを超えないsecondsの値でのみ機能する(most-positive-fixnumを参照)。

40.9 プロセッサーの実行時間

Emacsは、Emacsプロセスにより使用された経過時間(elapsed time)、プロセッサー時間(processor time)の両方にたいして、それらをリターンする関数とプリミティブをいくつか提供します。

Command: emacs-uptime &optional format

この関数はEmacsのuptime — このEmacsインスタンスが実行してから経過した、実世界における稼動時間。この文字列はオプション引数formatに応じて、format-secondsによりフォーマットされる。利用できるフォーマット記述子については、format-secondsを参照のこと。formatがnilまたは省略された場合のデフォルトは"%Y, %D, %H, %M, %z%S"。

インタラクティブに呼び出された場合には、エコーエリアにuptimeをプリントする。

Function: get-internal-run-time

This function returns the processor run time used by Emacs as a list of four integers: (sec-high sec-low microsec picosec), using the same format as current-time (see section 時刻).

この関数がリターンする値にはEmacsがプロセッサーを使用していない時間は含まれないこと、そしてEmacsプロセスが複数のスレッドをもつ場合には、すべてのEmacsスレッドにより使用されたプロセッサー時間の合計値がリターンされることに注意。

システムがプロセッサー実行時間を判断する方法を提供しない場合、get-internal-run-timeはcurrent-timeと同じ値をリターンする。

Command: emacs-init-time: この関数は、Emacs初期化(要約: スタートアップ時のアクション順序を参照)にかかった秒数を、文字列としてリターンする。インタラクティブに呼び出された場合には、それをエコーエリアにプリントする。

40.10 時間の計算

These functions perform calendrical computations using time values (see section 時刻). A value of nil for any of their time-value arguments stands for the current system time, and a single integer number stands for the number of seconds since the epoch.

Function: time-less-p t1 t2: これはtime値t1がtime値t2より小ならtをリターンする。

Function: time-subtract t1 t2: This returns the time difference t1 - t2 between two time values, as a time value. If you need the difference in units of elapsed seconds, use float-time (see section float-time) to convert the result into seconds.

Function: time-add t1 t2

This returns the sum of two time values, as a time value. One argument should represent a time difference rather than a point in time, either as a list or as a single number of elapsed seconds. Here is how to add a number of seconds to a time value:

(time-add time seconds)

Function: time-to-days time-value: This function returns the number of days between the beginning of year 1 and time-value.

Function: time-to-day-in-year time-value: This returns the day number within the year corresponding to time-value.

Function: date-leap-year-p year: この関数は、yearが閏年ならtをリターンする。

40.11 遅延実行のためのタイマー

You can set up a timer to call a function at a specified future time or after a certain length of idleness. A timer is a special object that stores the information about the next invocation times and the function to invoke.

Function: timerp object: This predicate function returns non-nil of object is a timer.

Emacsは、Lispプログラム内の任意の時点では、タイマーを実行できません。サブプロセスからの出力が受け入れ可能なときだけ、Emacsはタイマーを実行できます。つまり待機中や、待機することが可能な、sit-forやread-eventのような特定のプリミティブ関数内部でのみ、タイマーを実行できます。したがってEmacsがbusyなら、タイマーの実行は遅延するかもしれません。しかしEmacsがidleなら、実行される時刻は非常に正確になります。

quitにより、多くのタイマー関数が物事を不整合な状態に放置し得るので、ターマー関数呼び出し前にEmacsはinhibit-quitにtをバインドします。ほとんどのタイマー関数は多くの作業を行わないので、これは通常は問題にはなりません。しかし実際には、実行に長時間を要する関数を呼び出すタイマーは問題となる恐れがあります。タイマー関数がquitを許容する必要がある場合は、with-local-quitを使用するべきです(quitを参照)。たとえば、外部プロセスから出力を受け取るためにタイマー関数がaccept-process-outputを呼び出す場合、外部プロセスのハング時のC-gを確実に機能させるために、その呼び出しをwith-local-quit内部にラップすべきです。 For exam；ple, if a timer function calls to receive output from an external process, that call should be wrapped inside , to ensure that works if the external process hangs.

バッファー内容の変更のためにタイマー関数を呼び出すのは、通常は悪いアイデアです。これを行うときには、そのタイマーによる変更とユーザーのコマンドによる変更を分離して、単一のアンドゥエントリーが巨大になるのを防ぐために、バッファーの変更前後で、通常はundo-boundaryを呼び出すべきです。

タイマー関数はsit-forのようなEmacsに待機を発生させるような関数(時間の経過や入力の待機を参照)の呼び出しも避けるべきです。その待機中に別のタイマー(同じタイマーとう可能性さえある)が実行され得るので、これは予測不可能な効果を導く恐れがあります。特定時間の経過後に処理される必要があるタイマー関数は、新たなタイマーをスケジュールすることにより、これを行うことができます。

マッチデータを変更するかもしれない関数を呼び出すタイマー関数は、マッチデータの保存とリストアをするべきです。マッチデータの保存とリストアを参照してください。

Command: run-at-time time repeat function &rest args

これは時刻timeに、引数argsで関数functionを呼び出すタイマーをセットアップする。repeatが数値(整数か浮動小数点数)なら、そのタイマーはtime後の各repeat秒ごとに再実行されるようスケジュールされる。repeatがnilなら、そのタイマーは1回だけ実行される。

timeには、絶対時刻と相対時刻を指定できる。

絶対時刻は限定された種々フォーマットの文字列を使用して指定でき、すでに経過後の時刻であっても当日の時刻とみなされる。認識される形式は‘xxxx’、‘x:xx’、or ‘xx:xx’ (military time)、and ‘xxam’、‘xxAM’、‘xxpm’、‘xxPM’、‘xx:xxam’、‘xx:xxAM’、‘xx:xxpm’、‘xx:xxPM’のいずれか。時と分をの部分を区切るのは、コロンのかわりにピリオドも使用できる。

相対時刻は単位を付加した数字を、文字列として指定する。たとえば:

‘1 min’: 現在時刻から1分後を表す。
‘1 min 5 sec’: 現在時刻から65秒後を表す。
‘1 min 2 sec 3 hour 4 day 5 week 6 fortnight 7 month 8 year’: 現在時刻から丁度103ヵ月123日10862秒後を表す。

総体time値にたいして、Emacsは月を正確に30日、年を正確に365.25とみなす。

有用なフォーマットのすべてが文字列という訳ではない。timeが数字(整数か浮動小数点数)なら、それは秒で数えた相対時刻を指定する。encode-timeの結果は、timeにたいする絶対時刻の指定にも使用できる。

ほとんどの場合、最初に呼び出されている際はrepeatの効果はなく、time単独で時刻を指定する。例外が1つありtimeがtなら、エポックからrepeatの倍数秒ごとに毎回そのタイマーが実行される。これはdisplay-timeのような関数にとって有用である。

関数run-at-timeは、スケジュール済みの将来の特定アクションを識別するtime値をリターンする。cancel-timer(以下参照)の呼び出しに、この値を使用できる。

タイマーのリピートは名目上repeat秒ごとに毎回実行されますが、すべてのタイマー呼び出しは遅延する可能性があることを忘れないでください。1つの繰り返しの遅延が、次の繰り返しに影響を与えることはありません。たとえば3回分のスケジュール済みのタイマー繰り返しをカバーするほど計算等によりEmacsがbusyでも、それらは待機を開始して、連続してそのタイマー関数が3回呼び出されることになります(それらの間の別のタイマー呼び出しは想定していない)。最後の呼び出しからn秒より短くならずにタイマーを再実行したい場合には、repeat引数を使用しないでください。タイマー関数は、かわりにそのタイマーを明示的に再スケジュールするべきです。

User Option: timer-max-repeats: この変数の値は、以前スケジュールされていた呼び出しが止むを得ずに遅延された際に、タイマー関数がリピートによりまとめて呼び出される最大の回数を指定する

Macro: with-timeout (seconds timeout-forms…) body…

bodyを実行するが、seconds秒後に実行を諦める。タイムアップ前にbodyが終了したら、with-timeoutはbody内の最後のフォームの値をリターンする。ただし、タイムアウトによりbodyの実行が打ち切られた場合には、with-timeoutはtimeout-formsをすべて実行して、それの最後のフォームの値をリターンする。

このマクロは、seconds秒後に実行するタイマーをセットすることにより機能する。その時刻前にbodyが終了したらそのタイマーを削除し、タイマーが実際に実行されたらbodyの実行を終了して、それからtimeout-formsを実行する。

Lispプログラムでは、待機を行えるプリミティブをプログラムが呼び出している時のみタイマーを実行できるので、bodyが計算途中の間はwith-timeoutは実行を停止できない — そのプログラムがこれらのプリミティブのいずれかを呼び出したときのみ停止できる。そのため、bodyで長時間の計算を行う場合ではなく、入力を待機する場合だけwith-timeoutを使用すること。

あまりに長時間応答を待機するのを避けるために、関数y-or-n-p-with-timeoutはタイマーを使用するシンプルな方法を提供します。Yes-or-Noによる問い合わせを参照してください。

Function: cancel-timer timer: これはtimerにたいして要求されたアクションをキャンセルする。ここでtimerはタイマーであること。これは通常は以前にrun-at-timeかrun-with-idle-timerがリターンしたものである。この関数は、これらの関数の1つの呼び出しの効果をキャンセルする。指定した時刻が到来しても、特別ni何も起きないだろう。

The list-timers command lists all the currently active timers. There’s only one command available in the buffer displayed: c (timer-list-cancel) that will cancel the timer on the line under point.

40.12 アイドルタイマー

以下は、Emacsの特定の期間アイドル時に実行するタイマーをセットアップする方法です。それらをセットアップする方法とは別とすると、アイドルタイマーは通常のタイマーと同様に機能します。

Command: run-with-idle-timer secs repeat function &rest args

Emacsの次回secs秒間アイドル時に実行するタイマーをセットアップする。secsの値には数値、またはcurrent-idle-timeがリターンするタイプの値を指定できる。

repeatがnilなら、充分長い間Emacsがアイドルになった初回1会だけ、そのタイマーは実行される。大抵はrepeatが非nilの場合で、そのときはEmacsがsecs秒間アイドルになったときに、毎回そのタイマーが実行される。

関数run-with-idle-timerは、cancel-timer呼び出し時に使用できる、タイマー値をリターンする。

ユーザー入力の待機時にEmacsはアイドル(idle)となり、ユーザーが何らかの入力を与えるまでアイドルのままとなります。あるタイマーを5秒間のアイドルにセットすると、Emacsが最初に約5秒間アイドルになったとき、そのタイマーが実行されます。たとえrepeatが非nilでも、Emacsがアイドルであり続けるかぎり、そのタイマーが再実行されることはありません。アイドル期間は増加を続け、再び5秒に現象することはないからです。

アイドル時に、Emacsはガーベージコレクションや自動保存、サブプロセスからのデータ処理など、さまざまなことを行うことができます。しかし、これらの幕間劇がアイドルのクロックを0にリセットすることはないので、アイドルタイマーと干渉することはありません。600秒にセットされたアイドルタイマーは、たとえその10分間にサブプロセスの出力が何回到達しても、たとえガーベージコレクションや自動保存が行われても、ユーザーコマンドが最後に終了してから10分経過後に実行されるでしょう。

ユーザーが入力を与えると、その入力の実行の間、Emacsは非アイドルになります。それから再びアイドルとなり、繰り返すようにセットアップされたすべてのアイドルタイマーは、1つずつ異なる時刻に実行されるでしょう。

実行ごとに特定の量を処理するループを含んだり、(input-pending-p)が非nilのときにexitするアイドルタイマー関数を記述しないでください。このアプローチはとても自然に見えますが、2つの問題があります:

すべてのプロセスの出力をブロックする(Emacsは待機時のみプロセス出力を受け入れるため)。
その時刻の間に実行されるべきすべてのアイドルタイマーをブロックする。

同様に、secs引数がカレントのアイドル期間以下となるような、別のアイドルタイマー(同じアイドルタイマーも含む)をセットアップするアイドルタイマー関数を記述しないでください。そのようなタイマーはほとんど即座に実行され、Emacsが次回アイドルになるのを待機するかわりに、再現なく継続して実行されるでしょう。以下で説明するように、カレントのアイドル期間を適切に増加させて再スケジュールするのが、正しいアプローチです。

Function: current-idle-time

Emacsがアイドルなら、この関数はcurrent-timeで使用するのと同じ4つの整数リストのフォーマット(sec-high sec-low microsec picosec)で、Emacsがアイドルとなった期間をリターンする(時刻を参照)。

Emacsがアイドルでなければ、current-idle-timeはnilをリターンする。これはEmacsがアイドルかどうかテストする手軽な方法である。

current-idle-timeの主な用途は、アイドルタイマー関数が少し“休憩”したいときです。そのアイドルタイマー関数は、さらに数秒アイドル後に、同じ関数を再呼び出しするために、別のタイマーをセットアップできます。以下はその例です:

(defvar my-resume-timer nil
  "Timer for `my-timer-function' to reschedule itself, or nil.")

(defun my-timer-function ()
  ;; If the user types a command while my-resume-timer
  ;; is active, the next time this function is called from
  ;; its main idle timer, deactivate my-resume-timer.
  (when my-resume-timer
    (cancel-timer my-resume-timer))
  ...do the work for a while...
  (when taking-a-break
    (setq my-resume-timer
          (run-with-idle-timer
            ;; Compute an idle time break-length
            ;; more than the current value.
            (time-add (current-idle-time) break-length)
            nil
            'my-timer-function))))

40.13 端末の入力

このセクションでは、端末入力の記録や操作のための関数と変数を説明します。関連する関数につうては、Emacsのディスプレー表示を参照してください。

40.13.1 入力のモード

Function: set-input-mode interrupt flow meta &optional quit-char

この関数は、キーボード入力の読み取りにたいして、モードをセットする。interruptが非nilなら、Emacsは入力割り込み、nilならCBREAKモードを使用する。デフォルトのセッティングはシステムに依存する。いくつかのシステムでは、指定に関わらずに常にCBREAKモードを使用する。

EmacsがXと直接通信する際にはこの引数を無視して、それがEmacsの知る通信手段であれば割り込みを使用する。

flowが非nilなら、Emacsは端末への出力にたいしてXON/XOFFフロー制御(C-qとC-s)を使用する。これはCBREAK以外では効果がない。

引数metaは、127より上の文字コード入力にたいするサポートを制御する。metaがtなら、Emacsは8番目のビットがセットされた文字を、メタ文字に変換する。metaがnilなら、Emacsは8番目のビットを無視する。これは端末がそのビットをパリティビットとして使用する場合に必要となる。metaがtとnilのいずれでもなければ、Emacsは入力の8ビットすべてを変更せずに使用する。これは8ビット文字セットを使用する端末にたいして適している。

quit-charが非nilなら、それはquitに使用する文字を指定する。この文字は、通常はC-gである。quitを参照のこと。

current-input-mode関数は、Emacsがカレントで使用する入力モードのセッティングをリターンします。

Function: current-input-mode

この関数は、キーボード入力読み取りにたいする、カレントのモードをリターンする。これは、set-input-modeの引数に対応する、(interrupt flow meta quit)という形式のリストをリターンする。

interrupt: Emacsが割り込み駆動入力を使用時には非nil。nilならEmacsはCBREAKモードを使用している。
flow: Emacsが端末出力にXON/XOFFフロー制御(C-qとC-s)を使用していれば非nil。この値はinterruptがnilのときのみ意味がある。
meta: Emacsが入力文字の8番目のビットをメタ文字として扱う場合にはt。nilはEmacsがすべての入力文字の8ビット目をクリアーすることを意味する。その他の値は、Emacsが8ビットすべてを基本的な文字コードとして使用することを意味する。
quit: カレントでEmacsがquitに使用する文字で、通常はC-g。

40.13.2 入力の記録

Function: recent-keys

この関数は、キーボードかマウスからの最後の入力イベント300個を含んだベクターをリターンする。その入力イベントがキーシーケンスに含まれるか否かに関わらず、すべての入力イベントが含まれる。つまり、キーボードマクロにより生成されたイベントを含まない、最後の入力イベント300個を常に入手することになる。(キーボードマクロは、デバッグにとってより興味深いとはいえないので除外されている。そのマクロを呼び出したイベントを確認するだけで充分であるべきだ。)

clear-this-command-keys(コマンドループからの情報を参照)の呼び出すと、その直後この関数は空のベクターをリターンする。

Command: open-dribble-file filename

この関数は、filenameという名前のdribbleファイル(dribble file)をオープンする。dribbleファイルがオープンされたとき、キーボードとマウス(ただしキーボードマクロ由来は除く)からのそれぞれの入力イベントは、そのファイルに書き込まれる。非文字イベントは、‘<…>’で囲まれたプリント表現で表される。(パスワードのような)機密情報は、dribbleファイルへの記録を終了することに注意すること。

引数nilでこの関数を呼び出すことにより、nilファイルはクローズされる。

端末の出力のopen-termscriptを参照のこと。

40.14 端末の出力

端末出力関数は出力をテキスト端末に送信したり、その端末に送信した出力を追跡します。変数baud-rateは、Emacsが端末の出力スピードをどのように考慮すべきかを指示します。

User Option: baud-rate

この変数は、その端末のEmacsの認識する、その端末の出力スピードです。この変数をセットしても、実際のデータ転送スピードは変化しないが、この値はパディングのような計算に使用される。

これはテキスト端末でスクリーンの一部をスクロールしたり再描画すべきかどうかについての判定にも影響する。グラフィカルな端末での対応する機能については、強制的な再表示を参照のこと。

この値はボー(baud)で数えられる。

ネットワークを介して実行していて、そのネットワークの異なる部分が違うボーレートで機能している場合、Emacsがリターンする値はユーザーのローカル端末で使用される値と異なるかもしれません。いくつかのネットワークプロトコルは、ローカル端末のスピードでリモートマシンと対話するので、Emacsや他のプログラムは正しい値を得ることができますが、相手側はそうではありません。Emacsが誤った値をもつ場合には、最適よりも劣る判定をもたらします。この問題を訂正するためには、baud-rateをセットします。

Function: send-string-to-terminal string &optional terminal

This function sends string to terminal without alteration. Control characters in string have terminal-dependent effects. (If you need to display non-ASCII text on the terminal, encode it using one of the functions described in 明示的なエンコードとデコード.) This function operates only on text terminals. terminal may be a terminal object, a frame, or nil for the selected frame’s terminal. In batch mode, string is sent to stdout when terminal is nil.

この関数の1つの用途は、ダウンロード可能なファンクションキー定義をもつ端末上で、ファンクションキーを定義することである。たとえば、以下は(特定の端末で)ファンクションキー4を、4文字前方へ移動(そのコンピューターヘ文字C-u C-fを送信)するよう定義するには:

(send-string-to-terminal "\eF4\^U\^F")
     ⇒ nil

Command: open-termscript filename

この関数は、Emacsが端末へ送信したすべての文字を記録する、termscriptファイル(termscript file)をオープンする。リターン値はnil。termscriptファイルはEmacsのスクリーン文字化け問題、不正なTermcapエントリーや、実際のEmacsバグより頻繁に発生する、望ましくない端末オプションのセッティングの調査に有用である。どの文字が実際に出力されるか確信できれば、それらの文字が使用中のTermcap仕様に対応するかどうか、確実に判断できる。

(open-termscript "../junk/termscript")
     ⇒ nil

引数nilでこの関数を呼び出すことにより、termscriptファイルはクローズされる。

入力の記録のopen-dribble-fileも参照のこと。

40.15 サウンドの出力

Emacsを使用してサウンドを再生するためには、関数play-soundを使用します。特定のシステムだけがサポートされています。実際に処理を行うことができないシステムでplay-soundを呼び出すと、エラーが発生します。

サウンドはRIFF-WAVEフォーマット(‘.wav’)か、Sun Audioフォーマット(‘.au’)で格納されていなければなりません。

Function: play-sound sound

この関数は、指定されたサウンドを再生する。引数soundは、(sound properties...)という形式をもつ。ここでpropertiesはキーワード(特定のシンボルが特別に認識される)とそれに対応する値で交互に構成されている。

以下に、現在のところsound内で意味をもつキーワードと、それらの意味をテーブルに記した:

:file file: これは、再生するサウンドを含んだファイルを指定する。絶対ファイル名でなければ、ディレクトリーdata-directoryにたいして展開される。
:data data: これは、ファイルを参照する必要がないサウンドの再生を指定する。値dataは、サウンドファイルと同じバイトを含む文字列であること。わたしたちはユニバイト文字列の使用を推奨する。
:volume volume: これはサウンド再生での音の大きさを指定する。これは0から1までの数値であること。どんな値であれ、以前に指定されたボリュームがデフォルトとして使用される。
:device device: これはサウンドを再生するシステムデバイスを、文字列で指定する。デフォルトのデバイスはシステム依存である。

実際にサウンドを再生する前に、play-soundはリストplay-sound-functions内の関数を呼び出す。関数はそれぞれ1つの引数soundで呼び出される。

Command: play-sound-file file &optional volume device: この関数は、オプションでvolumeとdeviceを指定し、サウンドfileを再生する、代替インターフェイスである。

Variable: play-sound-functions: リストの関数は、サウンド再生前に呼び出される。関数はそれぞれ、そのサウンドを記述するプロパティリストを単一の引数として呼び出される。

40.16 X11キーシンボルの処理

システム固有のX11 keysym(key symbol: キーシンボル)を定義するには、変数system-key-alistをセットします。

Variable: system-key-alist

This variable’s value should be an alist with one element for each system-specific keysym. Each element has the form (code . symbol), where code is the numeric keysym code (not including the vendor-specific bit, -2**28), のビットは含まない)、symbolはそのファンクションキーの名前である。

たとえば(168 . mute-acute)は、数字コード -2**28 + 168のシステム固有キーを定義する(HP Xサーバーで使用される)。

このalistから、他のXサーバーのkeysymを除外することは重要ではない。実際に使用中のXサーバーが使用するkeysymが、これらと競合しないかぎり無害である.

この変数は常にカレント端末にたいしてローカルであり、バッファーローカルにできない。複数の端末を参照のこと。

You can specify which keysyms Emacs should use for the Control, Meta, Alt, Hyper, and Super modifiers by setting these variables:

Variable: x-ctrl-keysym

Variable: x-alt-keysym

Variable: x-meta-keysym

Variable: x-hyper-keysym

Variable: x-super-keysym

The name of the keysym that should stand for the Control modifier (respectively, for Alt, Meta, Hyper, and Super). For example, here is how to swap the Meta and Alt modifiers within Emacs:

(setq x-alt-keysym 'meta)
(setq x-meta-keysym 'alt)

40.17 batchモード

The command-line option ‘-batch’ causes Emacs to run noninteractively. In this mode, Emacs does not read commands from the terminal, it does not alter the terminal modes, and it does not expect to be outputting to an erasable screen. The idea is that you specify Lisp programs to run; when they are finished, Emacs should exit. The way to specify the programs to run is with ‘-l file’, which loads the library named file, or ‘-f function’, which calls function with no arguments, or ‘--eval=form’.

Any Lisp program output that would normally go to the echo area, either using message, or using prin1, etc., with t as the stream, goes instead to Emacs’s standard descriptors when in batch mode: message writes to the standard error descriptor, while prin1 and other print functions write to the standard output. Similarly, input that would normally come from the minibuffer is read from the standard input descriptor. Thus, Emacs behaves much like a noninteractive application program. (The echo area output that Emacs itself normally generates, such as command echoing, is suppressed entirely.)

Non-ASCII text written to the standard output or error descriptors is by default encoded using locale-coding-system (see section locale) if it is non-nil; this can be overridden by binding coding-system-for-write to a coding system of you choice (see section 明示的なエンコードとデコード).

Variable: noninteractive: Emacsがbatchモードで実行中なら、この変数は非nil。

40.18 セッションマネージャー

Emacsはアプリケーションのサスペンドとリスタートに使用される、Xセッション管理プロトコル(X Session Management Protocol)をサポートしています。Xウィンドウシステムでは、セッションマネージャー(session manager)と呼ばれるプログラムが、実行中アプリケーション追跡の責を負います。Xサーバーのシャットダウン時、セッションマネージャーはアプリケーションに状態を保存するか尋ね、それらが応答するまでシャットダウンを遅延します。アプリケーションがそのシャットダウンをキャンセルすることもできます。

セッションマネージャーがサスペンドされたセッションをリスタートする際には、これらのアプリケーションにたいして保存された状態をリロードするよう、個別に指示します。これはリストアする保存済みセッションが何かを指定する、特別なコマンドラインオプションを指定することにより行われます。これは、Emacsでは‘--smid session’という引数です。

Variable: emacs-save-session-functions

Emacsは、emacs-save-session-functionsと呼ばれるフックを介して、状態の保存をサポートする。セッションマネージャーがウィンドウシステムのシャットダウンを告げた際に、Emacsはこのフックを実行する。これらの関数は、カレントバッファーを一時バッファーにセットされて、引数なしで呼び出されるそれぞれの関数は、このバッファーにLispコードを追加するためにinsertを使用できる。最後にEmacsは、セッションファイル(session file)と呼ばれるファイル内にそのバッファーを保存する。

その後セッションマネージャーがEmacsを再開する際、Emacsはセッションファイルを自動的にロードする(ロードを参照)。これはスタートアップ中に呼び出される、emacs-session-restoreという名前の関数により処理される。要約: スタートアップ時のアクション順序を参照のこと。

emacs-save-session-functions内の関数が非nilをリターンすると、Emacsはセッションマネージャーにシャットダウンのキャンセルを要求します。

以下は、セッションマネージャによりEmacsがリストアされる際に、単に*scratch*にテキストを挿入する例です。

(add-hook 'emacs-save-session-functions 'save-yourself-test)

(defun save-yourself-test ()
  (insert "(save-current-buffer
  (switch-to-buffer \"*scratch*\")
  (insert \"I am restored\"))")
  nil)

40.19 デスクトップ通知

Emacs is able to send notifications on systems that support the freedesktop.org Desktop Notifications Specification and on MS-Windows. In order to use this functionality on POSIX hosts, Emacs must have been compiled with D-Bus support, and the notifications library must be loaded. See D-Bus in D-Bus integration in Emacs. The following function is supported when D-Bus support is available:

Function: notifications-notify &rest params

この関数は、引数paramsで指定された構成したパラメーターにより、D-Busを通じてデスクトップに通知を送信する。これらの引数は、交互になったキーワードと値のペアーで構成されていること。以下はサポートされているキーワードと値である:

:bus bus

D-Busのバス。この引数は、:session以外のバスを使用する場合のみ必要となる。

:title title

通知のタイトル。

:body text

通知ボディのテキスト。通知サーバーの実装に依存して‘"<b>bold text</b>"’のようなHTMLマークアップ、ハイパーリンク、イメージをテキストに含むことができる。HTML特殊文字は‘"Contact <postmaster@localhost>!"’のように、エンコードしなければならない。

:app-name name

その通知を送信するアプリケーション名。デフォルトはnotifications-application-name。

:replaces-id id

この通知が置換する通知のid。idは、notifications-notifyの以前の呼び出し結果でなければならない。

:app-icon icon-file

通知アイコンのファイル名。nilならアイコンは表示されない。デフォルトはnotifications-application-icon。

:actions (key title key title ...)

適用されるアクションのリスト。keyとtitleはどちらも文字列。(通常は通知クリックで呼び出される)デフォルトのアクションは、‘"default"’という名前であること。実装がそれを表示しないようにするには自由だが、titleは何でもよい。

:timeout timeout

timeoutは、通知が表示されてからその通知が自動的にクローズされるまでの、ミリ秒での時間。-1なら、その通知の有効期限は通知サーバーのセッティングに依存し、通知のタイプにより異なるかもしれない。0なら、その通知は失効しない。デフォルト値は-1。

:urgency urgency

緊急レベル。low、normal、criticalのいずれか。

:action-items

このキーワードが与えられると、そのアクションのtitle文字列はアイコン名として解釈される。

:category category

通知の種類で、文字列。標準のカテゴリーのリストは、Desktop Notifications Specificationを参照されたい。

:desktop-entry filename

これは‘"emacs"’のように、そのプログラムを呼び出すデスクトップファイル名の名前を指定する。

:image-data (width height rowstride has-alpha bits channels data)

これはそれぞれwidth、height、rowstride、およびalpha channel、bits per sample、channels、image dataの有無を記述するrawデータのイメージフォーマット。

:image-path path

これはURI(現在サポートされているのはURIスキーマは‘file://’のみ)、または‘$XDG_DATA_DIRS/icons’にあるfreedesktop.org準拠のアイコンテーマ名のいずれかを表される。

:sound-file filename

通知ポップアップ時に再生するサウンドファイルのパス。

:sound-name name

A themable named sound from the freedesktop.org sound naming specification from ‘$XDG_DATA_DIRS/sounds’, to play when the notification pops up. Similar to the icon name, only for sounds. An example would be ‘"message-new-instant"’.

:suppress-sound

それが可能なら、サーバーにすべてのサウンドの再生を抑制させる。

:resident

When set the server will not automatically remove the notification when an action has been invoked. The notification will remain resident in the server until it is explicitly removed by the user or by the sender. This hint is likely only useful when the server has the :persistence capability.

:transient

セットした場合、サーバーはその通知を過渡的なものとして扱い、もしそれが永続的であるべきなら、そのサーバーのpersistence能力をバイパスする。

:x position

:y position

その通知がポイントすべき、スクリーン上のXとYの座標を指定する。これらの引数は併せて使用しなければならない。

:on-action function

アクション呼び出し時に呼び出す関数。通知idとアクションのkeyは、引数としてその関数に渡される。

:on-close function

タイムアウトかユーザーにより通知がクローズされたときに呼び出す関数。通知idとクローズ理由reasonは、引数としてその関数に渡される。:

通知が失効した場合はexpired。
ユーザーが通知を却下したらdismissed。
notifications-close-notification呼び出しにより、 通知がクローズされたらclose-notification。
通知サーバーが理由を提供しなかったらundefined。

通知サーバーがどのパラメーターを受け入れるかのチェックは、notifications-get-capabilitiesを通じて行うことができる。

この関数は、整数の通知idをリターンする。このidはnotifications-close-notificationや、別のnotifications-notify呼び出しの:replaces-id引数で、通知アイテムの操作に使用できる。たとえば:

(defun my-on-action-function (id key)
  (message "Message %d, key \"%s\" pressed" id key))
     ⇒ my-on-action-function

(defun my-on-close-function (id reason)
  (message "Message %d, closed due to \"%s\"" id reason))
     ⇒ my-on-close-function

(notifications-notify
 :title "Title"
 :body "This is <b>important</b>."
 :actions '("Confirm" "I agree" "Refuse" "I disagree")
 :on-action 'my-on-action-function
 :on-close 'my-on-close-function)
     ⇒ 22

A message window opens on the desktop.  Press ``I agree''.
     ⇒ Message 22, key "Confirm" pressed
        Message 22, closed due to "dismissed"

Function: notifications-close-notification id &optional bus: この関数は、識別子idの通知をクローズする。busはD-Bus接続を表す文字列で、デフォルトは:session。

Function: notifications-get-capabilities &optional bus

通知サーバーの能力を、シンボルのリストでリターンする。busはD-Bus接続を表す文字列で、デフォルトは:session。期待され得る能力は以下のとおり:

:actions: そのサーバーはユーザーにたいする指定されたアクションを提供する。
:body: bodyのテキストをサポートする。
:body-hyperlinks: サーバーは通知内のハイパーリンクをサポートする。
:body-images: サーバーは通知内のイメージをサポートする。
:body-markup: サーバーは通知内のマークアップをサポートする。
:icon-multi: サーバーは与えられたイメージ配列内のすべてのフレームのアニメーションを描画できる。
:icon-static: 与えられたイメージ配列内の、正確に1フレームの表示をサポートする。この値は、:icon-multiと相互に排他である。
:persistence: サーバーは通知の永続性をサポートする。
:sound: サーバーは通知のサウンドをサポートする。

これらに加えて、ベンダー固有の能力は:x-gnome-foo-capのように、:x-vendorで始まる。

Function: notifications-get-server-information &optional bus

通知サーバーの情報を、文字列のリストでリターンする。busはD-Bus接続を表す文字列で、デフォルトは:session。リターンされるリストは(name vendor version spec-version)。

name: そのサーバーのプロダクト名。
vendor: ベンダー名。たとえば‘"KDE"’や‘"GNOME"’。
version: サーバーのバージョン番号。
spec-version: サーバーが準拠する仕様のバージョン。

spec_versionがnilなら、サーバーは‘"1.0"’以前の仕様をサポートする。

When Emacs runs on MS-Windows as a GUI session, it supports a small subset of the D-Bus notifications functionality via a native primitive:

Function: w32-notification-notify &rest params

This function displays an MS-Windows tray notification as specified by params. MS-Windows tray notifications are displayed in a balloon from an icon in the notification area of the taskbar.

Value is the integer unique ID of the notification that can be used to remove the notification using w32-notification-close, described below. If the function fails, the return value is nil.

The arguments params are specified as keyword/value pairs. All the parameters are optional, but if no parameters are specified, the function will do nothing and return nil.

The following parameters are supported:

:icon icon: Display icon in the system tray. If icon is a string, it should specify a file name from which to load the icon; the specified file should be a .ico Windows icon file. If icon is not a string, or if this parameter is not specified, the standard Emacs icon will be used.
:tip tip: Use tip as the tooltip for the notification. If tip is a string, this is the text of a tooltip that will be shown when the mouse pointer hovers over the tray icon added by the notification. If tip is not a string, or if this parameter is not specified, the default tooltip text is ‘Emacs notification’. The tooltip text can be up to 127 characters long (63 on Windows versions before W2K). Longer strings will be truncated.
:level level: Notification severity level, one of info, warning, or error. If given, the value determines the icon displayed to the left of the notification title, but only if the :title parameter (see below) is also specified and is a string.
:title title: The title of the notification. If title is a string, it is displayed in a larger font immediately above the body text. The title text can be up to 63 characters long; longer text will be truncated.
:body body: The body of the notification. If body is a string, it specifies the text of the notification message. Use embedded newlines to control how the text is broken into lines. The body text can be up to 255 characters long, and will be truncated if it’s longer. Unlike with D-Bus, the body text should be plain text, with no markup.

Note that versions of Windows before W2K support only :icon and :tip. The other parameters can be passed, but they will be ignored on those old systems.

There can be at most one active notification at any given time. An active notification must be removed by calling w32-notification-close before a new one can be shown.

To remove the notification and its icon from the taskbar, use the following function:

Function: w32-notification-close id: This function removes the tray notification given by its unique id.

40.20 ファイル変更による通知

Several operating systems support watching of filesystems for changes of files. If configured properly, Emacs links a respective library like inotify, kqueue, gfilenotify, or w32notify statically. These libraries enable watching of filesystems on the local machine.

リモートマシン上のファイルシステムの監視も可能です。Remote Files in The GNU Emacs Manualを参照してください。これはEmacsにリンク済みのライブラリーの、いずれか1つに依存する訳ではありません。

Since all these libraries emit different events on notified file changes, there is the Emacs library filenotify which provides a unified interface. Lisp programs that want to receive file notifications should always use this library in preference to the native ones.

Function: file-notify-add-watch file flags callback

fileに関するファイルシステムイベントの監視を追加する。これは、fileに関するファイルシステムイベントがEmacsに報告されるように取り計らう。

リターン値は、追加された監視のディスクリプター(descriptor)である。これのタイプは背景にあるライブラリーに依存し、以下の例に示すとおり、整数とみなすことはできない。これの比較には、equalを使用すること。

何らかの理由により、fileが監視不可能なら、この関数はエラーfile-notify-errorをシグナルする。

マウントされたファイルシステムでファイル変更を監視できないことがある。これはこの関数により検出されず、非nilのリターン値がfileの変更の通知を保証するものではない。

flagsは、何を監視するかセットするための、コンディションのリストである。以下のシンボルを含めることができる:

change: ファイル変更を監視。
attribute-change: パーミッションや変更時刻のような、ファイル属性の変更を監視。

fileがディレクトリーなら、そのディレクトリー内のすべてのファイルの変更が通知される。これは再帰的には機能しない。

何らかのイベント発生時には、以下の形式のeventを単一の引数として、Emacsは関数callbackを呼び出す:

(descriptor action file [file1])

descriptorは、この関数がリターンするオブジェクトと同じである。actionはイベントを示し、以下のシンボルのいずれかである:

created: fileが作成された。
deleted: fileが削除された。
changed: file’s contents has changed; with w32notify library, reports attribute changes as well
renamed: fileがfile1にリネームされた。
attribute-changed: fileの属性が変更された。
stopped: watching file has been stopped

Note that the w32notify library does not report attribute-changed events. When some file’s attribute, like permissions or modification time, has changed, this library reports a changed event. Likewise, the kqueue library does not report reliably file attribute changes when watching a directory.

The stopped event reports, that watching the file has been stopped. This could be because file-notify-rm-watch was called (see below), or because the file being watched was deleted, or due to another error reported from the underlying library.

fileおよびfile1は、イベントが報告されたファイルの名前である。たとえば:

(require 'filenotify)
     ⇒ filenotify

(defun my-notify-callback (event)
  (message "Event %S" event))
     ⇒ my-notify-callback

(file-notify-add-watch
  "/tmp" '(change attribute-change) 'my-notify-callback)
     ⇒ 35025468

(write-region "foo" nil "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/.#foo")
        Event (35025468 created "/tmp/foo")
        Event (35025468 changed "/tmp/foo")
        Event (35025468 deleted "/tmp/.#foo")

(write-region "bla" nil "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/.#foo")
        Event (35025468 changed "/tmp/foo")
        Event (35025468 deleted "/tmp/.#foo")

(set-file-modes "/tmp/foo" (default-file-modes))
     ⇒ Event (35025468 attribute-changed "/tmp/foo")

Whether the action renamed is returned, depends on the used watch library. Otherwise, the actions deleted and created could be returned in a random order.

(rename-file "/tmp/foo" "/tmp/bla")
     ⇒ Event (35025468 renamed "/tmp/foo" "/tmp/bla")

(delete-file "/tmp/bla")
     ⇒ Event (35025468 deleted "/tmp/bla")

Function: file-notify-rm-watch descriptor: descriptorに指定された、既存のファイル監視を削除する。descriptorは、file-notify-add-watchがリターンしたオブジェクトであること。

Function: file-notify-valid-p descriptor

Checks a watch specified by its descriptor for validity. descriptor should be an object returned by file-notify-add-watch.

A watch can become invalid if the file or directory it watches is deleted, or if the watcher thread exits abnormally for any other reason. Removing the watch by calling file-notify-rm-watch also makes it invalid.

(make-directory "/tmp/foo")
     ⇒ Event (35025468 created "/tmp/foo")

(setq desc
      (file-notify-add-watch
        "/tmp/foo" '(change) 'my-notify-callback))
     ⇒ 11359632

(file-notify-valid-p desc)
     ⇒ t

(write-region "bla" nil "/tmp/foo/bla")
     ⇒ Event (11359632 created "/tmp/foo/.#bla")
        Event (11359632 created "/tmp/foo/bla")
        Event (11359632 changed "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo/.#bla")

;; Deleting a file in the directory doesn't invalidate the watch.
(delete-file "/tmp/foo/bla")
     ⇒ Event (11359632 deleted "/tmp/foo/bla")

(write-region "bla" nil "/tmp/foo/bla")
     ⇒ Event (11359632 created "/tmp/foo/.#bla")
        Event (11359632 created "/tmp/foo/bla")
        Event (11359632 changed "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo/.#bla")

;; Deleting the directory invalidates the watch.
;; Events arrive for different watch descriptors.
(delete-directory "/tmp/foo" 'recursive)
     ⇒ Event (35025468 deleted "/tmp/foo")
        Event (11359632 deleted "/tmp/foo/bla")
        Event (11359632 deleted "/tmp/foo")
        Event (11359632 stopped "/tmp/foo")

(file-notify-valid-p desc)
     ⇒ nil

40.21 動的にロードされるライブラリー

ダイナミックにロードされるライブラリー(dynamically loaded library)とは、その機能が最初に必要になったときに、オンデマンドでロードされるライブラリーです。Emacsは自身の機能をサポートするライブラリーのオンデマンドロードのように、それらをサポートします。

Variable: dynamic-library-alist

これはダイナミックライブラリーと、それらを実装する外部ライブラリーファイルのalistである。

要素はそれぞれ、(library files…)という形式のリストである。ここでcarはサポートされた外部ライブラリーを表すシンボルで、残りはそのライブラリーにたいして候補となるファイル名を与える文字列である。

Emacsは、このリスト内のファイル出現順で、そのライブラリーのロードを試みる。何も見つからない場合、そのEmacsセッションはライブラリーにアクセスできず、それが提供する機能は利用できない。

いくつかのプラットフォーム上におけるイメージのサポートは、この機能を使用している。以下は、MS-Windows上でイメージをサポートするために、この変数をセットする例である:

(setq dynamic-library-alist
      '((xpm "libxpm.dll" "xpm4.dll" "libXpm-nox4.dll")
        (png "libpng12d.dll" "libpng12.dll" "libpng.dll"
             "libpng13d.dll" "libpng13.dll")
        (jpeg "jpeg62.dll" "libjpeg.dll" "jpeg-62.dll"
              "jpeg.dll")
        (tiff "libtiff3.dll" "libtiff.dll")
        (gif "giflib4.dll" "libungif4.dll" "libungif.dll")
        (svg "librsvg-2-2.dll")
        (gdk-pixbuf "libgdk_pixbuf-2.0-0.dll")
        (glib "libglib-2.0-0.dll")
        (gobject "libgobject-2.0-0.dll")))

イメージタイプpbmとxbmは外部ライブラリーに依存せず、Emacsで常に利用可能なので、この変数内にエントリーがないことに注意。

これは、外部ライブラリーへのアクセスにたいする、一般的な機能を意図したものではないことにも注意されたい。Emacsにとって既知のライブラリーだけが、これを通じてロードできる。

与えられたlibraryが、Emacsに静的にリンクされている場合、この変数は無視される。

40.22 Security Considerations

Like any application, Emacs can be run in a secure environment, where the operating system enforces rules about access and the like. With some care, Emacs-based applications can also be part of a security perimeter that checks such rules. Although the default settings for Emacs work well for a typical software development environment, they may require adjustment in environments containing untrusted users that may include attackers. Here is a compendium of security issues that may be helpful if you are developing such applications. It is by no means complete; it is intended to give you an idea of the security issues involved, rather than to be a security checklist.

File local variables

A file that Emacs visits can contain variable settings that affect the buffer visiting that file; See section ファイルローカル変数. Similarly, a directory can specify local variable values common to all files in that directory; see ディレクトリーローカル変数. Although Emacs takes some effort to protect against misuse of these variables, a security hole can be created merely by a package setting safe-local-variable too optimistically, a problem that is all too common. To disable this feature for both files and directories, set enable-local-variables to nil.

Access control

Although Emacs normally respects access permissions of the underlying operating system, in some cases it handles accesses specially. For example, file names can have handlers that treat the files specially, with their own access checking. See section 特定のファイル名の“Magic”の作成. Also, a buffer can be read-only even if the corresponding file is writeable, and vice versa, which can result in messages such as ‘File passwd is write-protected; try to save anyway? (yes or no)’. See section 読み取り専用のバッファー.

Authentication

Emacs has several functions that deal with passwords, e.g., read-passwd. See section パスワードの読み取り. Although these functions do not attempt to broadcast passwords to the world, their implementations are not proof against determined attackers with access to Emacs internals. For example, even if Elisp code uses clear-string to scrub a password from its memory after using it, remnants of the password may still reside in the garbage-collected free list. See section 文字列の変更.

Code injection

Emacs can send commands to many other applications, and applications should take care that strings sent as operands of these commands are not misinterpreted as directives. For example, when using a shell command to rename a file a to b, do not simply use the string mv a b, because either file name might start with ‘-’, or might contain shell metacharacters like ‘;’. Although functions like shell-quote-argument can help avoid this sort of problem, they are not panaceas; for example, on a POSIX platform shell-quote-argument quotes shell metacharacters but not leading ‘-’. On MS-Windows, quoting for ‘%’ assumes none of the environment variables have ‘^’ in their name. See section shell引数. Typically it is safer to use call-process than a subshell. See section 同期プロセスの作成. And it is safer yet to use builtin Emacs functions; for example, use (rename-file "a" "b" t) instead of invoking mv. See section ファイルの名前と属性の変更.

Coding systems

Emacs attempts to infer the coding systems of the files and network connections it accesses. See section コーディングシステム. If Emacs infers incorrectly, or if the other parties to the network connection disagree with Emacs’s inferences, the resulting system could be unreliable. Also, even when it infers correctly, Emacs often can use bytes that other programs cannot. For example, although to Emacs the null byte is just a character like any other, many other applications treat it as a string terminator and mishandle strings or files containing null bytes.

Environment and configuration variables

POSIX specifies several environment variables that can affect how Emacs behaves. Any environment variable whose name consists entirely of uppercase ASCII letters, digits, and the underscore may affect the internal behavior of Emacs. Emacs uses several such variables, e.g., EMACSLOADPATH. See section ライブラリー検索. On some platforms some environment variables (e.g., PATH, POSIXLY_CORRECT, SHELL, TMPDIR) need to have properly-configured values in order to get standard behavior for any utility Emacs might invoke. Even seemingly-benign variables like TZ may have security implications. See section オペレーティングシステムの環境.

Emacs has customization and other variables with similar considerations. For example, if the variable shell-file-name specifies a shell with nonstandard behavior, an Emacs-based application may misbehave.

Installation

When Emacs is installed, if the installation directory hierarchy can be modified by untrusted users, the application cannot be trusted. This applies also to the directory hierarchies of the programs that Emacs uses, and of the files that Emacs reads and writes.

Network access

Emacs often accesses the network, and you may want to configure it to avoid network accesses that it would normally do. For example, unless you set tramp-mode to nil, file names using a certain syntax are interpreted as being network files, and are retrieved across the network. See The Tramp Manual in The Tramp Manual.

Race conditions

Emacs applications have the same sort of race-condition issues that other applications do. For example, even when (file-readable-p "foo.txt") returns t, it could be that foo.txt is unreadable because some other program changed the file’s permissions between the call to file-readable-p and now. See section アクセシビリティのテスト.

Resource limits

When Emacs exhausts memory or other operating system resources, its behavior can be less reliable, in that computations that ordinarily run to completion may abort back to the top level. This may cause Emacs to neglect operations that it normally would have done.

41 配布用 Lispコードの準備

Emacsは、Emacs Lispコードをユーザーに配布するための、標準的な方法を提供します。パッケージ(package)は、ユーザーが簡単にダウンロード、インストール、アンインストール、および更新できるような方法でフォーマットおよび同梱された、1つ以上のファイルのコレクションです。

以降のセクションではパッケージを作成する方法、およびそれを他の人がダウンロードできるように、パッケージアーカイブ(package archive)に配置する方法を説明します。パッケージングシステムのユーザーレベル機能の説明は、Packages in The GNU Emacs Manualを参照してください。

41.1 パッケージ化の基礎

パッケージはシンプルパケージ(simple package)か複数ファイルパッケージ(multi-file package)のいずれかです。シンプルパッケージは単一のEmacs Lispファイル内に格納される一方、複数ファイルパッケージはtarファイル(複数のLispファイルとマニュアルのような非Lispファイルが含まれる可能性がある)に格納されます。

通常の使い方では、シンプルパッケージと複数ファイルパッケージとの違いは、比較的重要ではありません。Package Menuインターフェースでは、それらの間に差異はありません。しかし以降のセクションで説明するように、それらを作成する手順は異なります。

パッケージ(シンプルか複数ファイル)はそれぞれ、特定の属性(attributes)をもっています:

Name: 短い単語(たとえば‘auctex’)。これは通常、そのプログラム内でシンボルプレフィクスとしても仕様される(Emacs Lispコーディングの慣習を参照)。
Version: A version number, in a form that the function version-to-list understands (e.g., ‘11.86’). Each release of a package should be accompanied by an increase in the version number so that it will be recognized as an upgrade by users querying the package archive.
Brief description: そのパッケージがPackage Menuにリストされる際に、これが表示される。理想的には36文字以内で、単一行を占めるべきである。
Long description: これはC-h P(describe-package)により作成されたバッファーに表示され、これの後にそのパッケージの簡単な説明(brief description)とインストール状態(installation status)が続く。通常これは複数行に渡り、そのパッケージの能力と、インストール後に使用を開始するための方法を完全に記述すること。
Dependencies: A list of other packages (possibly including minimal acceptable version numbers) on which this package depends. The list may be empty, meaning this package has no dependencies. Otherwise, installing this package also automatically installs its dependencies, recursively; if any dependency cannot be found, the package cannot be installed.

コマンドpackage-install-file、またはPackage Menuのいずれかを介したパッケージのインストールでは、package-user-dirにname-versionという名前のサブディレクトリーが作成される。ここでnameはパッケージ名、versionはバージョン番号である(たとえば~/.emacs.d/elpa/auctex-11.86/)。わたしたちはこれを、そのパッケージのコンテンツディレクトリー(content directory)と呼んでいます。これは、Emacsがパッケージのコンテンツ(シンプルパッケージでは単一のLispファイル、または複数ファイルパッケージから抽出されたファイル)を配置する場所です。

その後Emacsは、autoloadマジックコメント(autoloadを参照)にたいして、このコンテンツディレクトリー内のすべてのLispファイルを検索します。これらのautoload定義は、コンテンツディレクトリーのname-autoloads.elという名前のファイルに保存されます。これらは通常、そのパッケージ内で定義された主要なユーザーコマンドのautoloadに使用されますが、auto-mode-alistへの要素の追加(Emacsがメジャーモードを選択する方法を参照)等、別のタスクを行うこともできます。パッケージは通常、その中で定義された関数と変数のすべてをautoloadしないことに注意してください — 通常はそのパッケージの使用を開始するために呼び出される一握りのコマンドだけがautoloadされます。それから、Emacsはそのパッケージ内のすべてのLispファイルをバイトコンパイルします。

インストール後、インストールされたパッケージはロード済み(loaded)になります。Emacsはload-pathにコンテンツディレクトリーを追加して、name-autoloads.el内のautoload定義を評価します。

Emacsのスタートアップ時は常に、インストール済みパッケージをロードするために、自動的に関数package-initializeが呼び出されます。これはinitファイルと、(もしあれば)abbrevファイルのロード後、かつafter-init-hookの実行前に行われます(要約: スタートアップ時のアクション順序を参照)。ユーザーオプションpackage-enable-at-startupがnilなら、自動的なパッケージのロードは無効です。

Command: package-initialize &optional no-activate

This function initializes Emacs’ internal record of which packages are installed, and loads them. The user option package-load-list specifies which packages to load; by default, all installed packages are loaded. If called during startup, this function also sets package-enable-at-startup to nil, to avoid accidentally loading the packages twice. See Package Installation in The GNU Emacs Manual.

オプション引数no-activateが非nilなら、インストール済みパッケージを実際にロードせずに、このレコードを更新する。これは内部でのみ使用される。

41.2 単純なパッケージ

シンプルパッケージは単一のEmacs Lispソースファイルで構成されます。このファイルは、Emacs Lispライブラリーのヘッダー規約に準拠していなればなりません(Emacsライブラリーのヘッダーの慣習を参照)。以下の例に示すように、そのパッケージの属性は種々のヘッダーから取得されます:

;;; superfrobnicator.el --- Frobnicate and bifurcate flanges

;; Copyright (C) 2011 Free Software Foundation, Inc.


;; Author: J. R. Hacker <jrh@example.com>
;; Version: 1.3
;; Package-Requires: ((flange "1.0"))
;; Keywords: multimedia, frobnicate
;; URL: http://example.com/jrhacker/superfrobnicate

…

;;; Commentary:

;; This package provides a minor mode to frobnicate and/or
;; bifurcate any flanges you desire.  To activate it, just type
…

;;;###autoload
(define-minor-mode superfrobnicator-mode
…

そのパッケージの名前は1行目のファイル名の拡張子を除いた部分と同じです。ここでは、それは‘superfrobnicator’です。

brief description(簡単な説明)も1行目から取得されます。ここでは、それは‘Frobnicate and bifurcate flanges’(訳注: ‘flangeをフロブニケートして二股化する’のフロブニケートとは、ある技術にたいする無目的で非生産的な具体的行為を意味する)です。

バージョン番号は、もしあれば‘Package-Version’ヘッダー、それ以外は‘Version’ヘッダーから取得されます。これらのヘッダーのいずれかが、提供されていなればなりません。ここのバージョン番号は1.3です。

そのファイルに‘;;; Commentary:’セクションがあれば、そのセクションは長い説明(long description)として使用されます。(その説明を表示する際、Emacsは‘;;; Commentary:’の行と、コメント内のコメント文字列を省力する。)

そのファイルに‘Package-Requires’ヘッダーがあれば、それはパッケージの依存関係(package dependencies)として使用されます。上の例では、パッケージはバージョン1.0以上の‘flange’パッケージに依存します。‘Package-Requires’ヘッダーの説明は、Emacsライブラリーのヘッダーの慣習を参照してください。このヘッダーが省略された場合、そのパッケージに依存関係はありません。

ヘッダー‘Keywords’と‘URL’はオプションですが、含めることを推奨します。コマンドdescribe-packageは、出力にリンクを追加するためにこれらを使用します。‘Keywords’ヘッダーには、finder-known-keywordsリストからの標準的キーワードを少なくとも1つ含めるべきです。

ファイルにはパッケージ化の基礎で説明したように、1つ以上のautoloadマジックコメントも含めるべきです。上の例では、マジックコメントによりsuperfrobnicator-modeが自動ロードされます。

See section パッケージアーカイブの作成と保守, for an explanation of how to add a single-file package to a package archive.

41.3 複数ファイルのパッケージ

複数ファイルパッケージは、単一ファイルパッケージより作成の手軽さが少し劣りますが、より多くの機能を提供します。複数ファイルパッケージには複数のEmacs Lispファイル、Infoマニュアル、および(イメージのような)他のファイルタイプを含めることができます。

インストールに先立ち、複数パッケージはファイルとしてパッケージアーカイブに含まれます。このtarファイルはname-version.tarという名前でなければなりません。ここでnameはパッケージ名、versionはバージョン番号です。tarのコンテンツは一度解凍されたなら、コンテンツディレクトリcontent directory)であるname-versionという名前のディレクトリーにすべて解凍されなければなりません(パッケージ化の基礎を参照)。このコンテンツディレクトリーのサブディレクトリーにも、ファイルが抽出されるかもしれません。

One of the files in the content directory must be named name-pkg.el. It must contain a single Lisp form, consisting of a call to the function define-package, described below. This defines the package’s attributes: version, brief description, and requirements.

たとえば、複数ファイルパッケージとしてsuperfrobnicatorのバージョン1.3を配布する場合、tarファイルはsuperfrobnicator-1.3.tarになります。これのコンテンツはsuperfrobnicator-1.3に解凍され、そのうちの1つはファイルsuperfrobnicator-pkg.elになるでしょう。

Function: define-package name version &optional docstring requirements

この関数はパッケージを定義する。nameは、そのパッケージの名前(文字列)、versionは関数version-to-listが理解できる形式のバージョン(文字列)docstringは簡単な説明(brief description)。

requirementsは、必要となるパッケージとそれらのバージョン番号。このリスト内の各要素は(dep-name dep-version)という形式であること。ここでdep-nameはその依存するパッケージ名が名前であるようなシンボル、dep-versionは依存するパッケージのバージョン番号(文字列)である。

コンテンツディレクトリーにREADMEという名前のファイルがあれば、それは長い説明(long description)として使用されます。

コンテンツディレクトリーにdirという名前のファイルがあれば、install-infoで作成されるInfoディレクトリーファイル名と▽みなされます。Invoking install-info in Texinfoを参照してください。関係のあるInfoファイルも、このコンテンツディレクトリー内に解凍される必要があります。この場合、そのパッケージがアクティブ化されたとき、Emacsは自動的にInfo-directory-listにコンテンツディレクトリーを追加します。

パッケージ内に、.elcファイルを含めないでください。これらは、そのパッケージのインストール時に作成されます。ファイルがバイトコンパイルされる順序を制御する方法は存在しないことに注意してください。

name-autoloads.elという名前のファイルを含めてはなりません。このファイルは、そのパッケージのautoload定義のために予約済みです(パッケージ化の基礎を参照)。これはパッケージのインストール時に、そのパッケージ内のすべてのLispファイルからautoloadマジックコメントを検索する際、自動的に作成されます。

複数パッケージファイルが、(イメージのような)補助的なデータファイルを含む場合、パッケージ内のLispファイルは変数load-file-nameを通じて、それらのファイルを参照できます(ロードを参照)。以下は例です:

(defconst superfrobnicator-base (file-name-directory load-file-name))

(defun superfrobnicator-fetch-image (file)
  (expand-file-name file superfrobnicator-base))

41.4 パッケージアーカイブの作成と保守

Via the Package Menu, users may download packages from package archives. Such archives are specified by the variable package-archives, whose default value contains a single entry: the archive hosted by the GNU project at https://elpa.gnu.org. This section describes how to set up and maintain a package archive.

User Option: package-archives

この変数の値は、Emacsパッケージマネージャーが認識する、パッケージアーカイブのリストである。

このalistの要素はそれぞれが1つのアーカイブに対応し、(id . location)という形式であること。ここでidはパッケージ名(文字列)、locationは文字列であるようなベースロケーション(base location)である。

If the base location starts with ‘http:’ or ‘https:’, it is treated as an HTTP(S) URL, and packages are downloaded from this archive via HTTP(S) (as is the case for the default GNU archive).

Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file access. Such local archives are mainly useful for testing.

パッケージアーカイブは、そのパッケージ、および関連するファイルが格納された、単なるディレクトリーです。HTTPを介してそのアーカイブに到達できるようにしたければ、このディレクトリーがウェブサーバーにアクセスできなければなりません。これを達成する方法は、このマニュアルの範囲を超えます。

手軽なのは、package-xを通じてパッケージアーカイブのセットアップと更新を行う方法です。これはEmacsに含まれていますが、デフォルトではロードされません。ロードするにはM-x load-library RET package-x RET、または(require 'package-x)をinitファイルに追加します。Lisp Libraries in The GNU Emacs Manualを参照してください。一度ロードされれば、以下を使用できます:

User Option: package-archive-upload-base

この変数の値は、ディレクトリー名としてのパッケージアーカイブのベースロケーションである。package-xライブラリー内のコマンドは、このベースロケーションを使用することになる。

このディレクトリー名は絶対ファイル名であること。パッケージアーカイブが別マシン上にある場合には、/ssh:foo@example.com:/var/www/packages/のようなリモート名を指定できる。Remote Files in The GNU Emacs Manualを参照のこと。

Command: package-upload-file filename

このコマンドはファイル名filenameの入力を求め、そのファイルをpackage-archive-upload-baseにアップロードする。このファイルはシンプルパッケージ(.elファイル)、または複数ファイルパッケージ(.tarファイル)のいずれかでなければならず、それ以外ならエラーが発生する。そのパッケージの属性は自動的に解凍され、アーカイブのコンテンツリストは、この情報でアップロードされる。

package-archive-upload-baseが有効なディレクトリーを指定しない場合、この関数はインタラクティブにそれの入力を求める。そのディレクトリーが存在しなければ作成する。このディレクトリーに、初期コンテンツをもつ必要はない(最初に空のアーカイブを作成するために、このコマンドを使用できる)。

Command: package-upload-buffer: このコマンドはpackage-upload-fileと似ているが、パッケージファイルの入力を求めずに、カレントバッファーのコンテンツをアップロードする。カレントバッファーはシンプルパッケージ(.elファイル)か複数ファイルパッケージ(.tarファイル)をvisitしていなればならず、それ以外ならエラーが発生する。

アーカイブ作成後、それがpackage-archives内になければ、Package Menuインターフェースからアクセスできないことを忘れないでください。

公的なパッケージアーカイブの保守には責任が併ないます。アーカイブからEmacsユーザーがパッケージをインストールする際、それらのパッケージはそのユーザーの権限において、任意のコードを実行できるようになります(これはパッケージにたいしてだけでなく、一般的なEmacsコードにたいしても真といえる)。そのため、アーカイブの保守を保つとともに、ホスティングシステムが安全であるよう維持するべきです。

暗号化されたキーを使用してパッケージにサイン(sign)するのが、パッケージのセキュリティーを向上する1つの方法です。gpgのprivateキーとpublicキーを生成してあれば、以下のようにそのパッケージにサインするためにgpgを使用できます:

gpg -ba -o file.sig file

単一ファイルパッケージにたいしては、fileはそのパッケージのLispファイルです。複数ファイルパッケージではそのパッケージのtarファイルです。同じ方法により、アーカイブのコンテンツファイルにもサインできます。これを行うには、パッケージと同じディレクトリーで、.sigファイルを利用可能できるようにしてください。ダウンロードする人にたいしても、http://pgp.mit.edu/のようなキーサーバーにアップロードすることにより、publicキーを利用できるようにするべきです。その人がアーカイブからパッケージをインストールする際、には署名の検証にpublicキーを使用できます。

これらの方法についての完全な説明は、このマニュアルの範囲を超えます。暗号化キーとサインに関する詳細はGnuPG in The GNU Privacy Guard Manual、Emacsに付属するGNU Privacy Guardへのインターフェースについては、EasyPG in Emacs EasyPG Assistant Manualを参照してください。

Appendix A Emacs 25 Antinews

For those users who live backwards in time, here is information about downgrading to Emacs version 25.3. We hope you will enjoy the greater simplicity that results from the absence of many Emacs 26.1 features.

A.1 Old Lisp Features in Emacs 25

The concurrency features have been removed. Even in its limited “mostly cooperative” form, with only one Lisp thread running at any given time, it made Emacs significantly more complex for Lisp programs that need to work correctly in the presence of additional threads.
Handling of file attributes has been simplified by discarding the accessor functions, such as file-attribute-type and file-attribute-modification-time. Real Lisp programmers always access the individual attributes by their ordinal numbers, and can recite those numbers in their sleep.
The networking code is back at its pristine simplicity, as we deleted the use of asynchronous DNS resolution, connection, and TLS negotiation for TLS streams. You no longer need to consider the resulting complexity and interesting race conditions when you write Lisp programs that use network communications. As a direct consequence, the :complete-negotiation parameter of gnutls-boot has become unnecessary, and was removed—just one example of how removal of asynchronicity simplifies Emacs.
We’ve removed the puny.el library, so Web sites with non-ASCII URLs are no longer easily accessible. But such sites become more and more rare as you move back in time, so having a specialized library for their support was deemed an unnecessary maintenance burden.
The time conversion functions current-time-string, current-time-zone, decode-time, format-time-string, and set-time-zone-rule no longer accept integer offsets as time zone rules, to make it more of a challenge to convert foreign timestamps. Also, format-time-string no longer converts ‘%q’ to the calendar quarter, as that is something you can easily do for yourself.
Field numbers like ‘%2$’ in format specifiers are no longer available. We decided that their use makes code reading and comprehension much harder, and that having them is unjustified in the past where similar features in popular C libraries will also be gone.
Since the built-in capability to display line numbers has been removed (see Antinews in The GNU Emacs Manual), we’ve also deleted the line-number-display-width function and the support for the display-line-numbers-disable property, as Lisp programs that do their own display layout decisions no longer need to cater to this tricky feature.
Regular expressions have been simplified by removing support for Unicode character properties in the [:blank:] regexp class. As result, this class will match only spaces and tabs. Once again, this is in line with diminishing importance of Unicode as you move back in time.
For similar reasons, we removed the function char-from-name. It should be easy enough to access the full list of Unicode characters returned by ucs-names instead, for as long as Unicode support in Emacs exists (which shouldn’t be too long).
Various functions that accept file names as arguments, such as file-attributes, file-symlink-p, and make-symbolic-link gained back the special support for file names quoted with ‘/:’, and they now interpret ‘~’ in symlink targets as you’d expect: to mean your home directory. The confusing differences between the operation of these functions in interactive and non-interactive invocations has been removed.
Several functions that create or rename their files now treat their destination specially if it happens to be a directory, even when its name does not appear to be that of a directory. For example, (rename-file "A" "B") no longer renames A to B if B happens to be a directory. This is so that dealing with files becomes more of an adventure.
The format function now returns new strings in more cases, to place more stress on the Emacs memory manager and thereby test Emacs better.
The function assoc has been simplified by removing its third optional argument. It now always uses equal for comparison. Likewise, alist-get always uses assq, and map-get and map-put always use eql for their comparisons.
Numeric comparisons and the functions format, make-hash-table, min, max and logb now occasionally round values internally to make their results less predictable.
The functions ffloor, fceilingl, ftruncate and fround now accept integer arguments. Conversely, functions like decode-char that accept floating-point integers now accept arguments that are not integers. In both cases the results are amusingly nonsensical sometimes.
GnuTLS cryptographic functions are no longer available in Emacs. We have decided that the needs for such functionality are deteriorating, and their cumbersome interfaces make them hard to use.
We have removed support for records of user-defined types, and cl-defstruct no longer uses records. This removes the potential for quite a few places where existing and past code could be broken by records.
You can again use string-as-unibyte, string-make-multibyte, and other similar functions, without being annoyed by messages about their deprecation. This is in preparation for removal of multibyte text from Emacs in the distant past.
The string-version-lessp function has been removed, to encourage programmers to use their own idiosyncratic methods to determine whether one version string precedes another.
The function read-color no longer displays color names using each color as the background. We have determined that this surprises users and produces funny inconsistent results on color-challenged terminals.
Support for 24-bit color on text terminals has been dropped, since it wasn’t needed long ago.
We removed the function file-name-case-insensitive-p, as testing for the OS symbol should be enough for the observable past to come, and learning to use yet another API is a burden.
The function read-multiple-choice is also gone, in recognition of the fact that nothing makes Emacs Lisp hackers rejoice more than the need to sit down and write yet another interactive question-and-answer function, and make it optimal for each specific case.
The function add-variable-watcher and the corresponding debugger command debug-on-variable-change have been removed. They make debugging more complicated, while examining the value of a variable at each stop point is easy enough to cover the same use cases. Let simplicity rule!
The function mapcan is gone; use mapcar instead, and process the resulting list as you see fit.
Low-level list functions like length and member can now loop indefinitely when given cyclic lists, causing Emacs to freeze. This can help these functions run a tiny bit faster in the usual case where the input is not cyclic.
The write-region function no longer propagates its lockname argument to file name handlers.
You can once again write a Lisp program that returns funny random values from file-attributes by having another process alter the filesystem while Emacs is accessing the file. This can give rise to some interesting applications in the near past.
The functions file-attributes, file-symlink-p, and make-symbolic-link now quietly mutate the target of a local symbolic link in some cases, to make it more of a challenge to deal with arbitrary symlinks in Emacs code.
The error file-missing has been removed; operations now lump such errors into the file-error category instead.
The function delete-directory now signals an error if operating recursively and some other process deletes the directory before this function gets to it.
The dutch input method now attempts to support Turkish too, albeit incorrectly. Also, it converts ‘IJ’ and ‘ij’ to special characters instead of leaving them alone.
Non-breaking hyphens and approximations to quotes are now displayed just with the escape-glyph face instead of having faces of their own. This is simpler and gives the user amusing puzzles to solve when viewing text containing these characters.
The user option electric-quote-context-sensitive and the variable electric-quote-inhibit-functions, so that electric quoting is simpler and more likely to do the wrong thing.
The user option text-quoting-style has been removed, and is now just a variable.
We have removed the functions file-name-quote, file-name-unquote, and file-name-quoted-p. Writing code that checks whether a file name is already quoted is easy, and doubly quoting a file name should not produce any problems for well-written Lisp code.
Frame parameters like z-group, min-width, parent-frame, delete-before, etc. have been removed. Emacs should not replace your window-manager, certainly not as window-managers become less and less capable.
We decided that the format of mode line and header line should be customizable only based on buffers; the mode-line-format and header-line-format window parameters have been removed.
Emacs now normally builds a limited movemail substitute that retrieves POP3 email only via insecure channels, and the configure-time option --with-mailutils has been removed. This simplifies Emacs setup when security is not important.
The configure-time option --enable-gcc-warnings=warn-only has been removed, so that build-time warnings are always fatal now.
The configure-time option --disable-build-details has been removed. This way, Emacs builds are unique and irreproducible.
The variable emacs-version now includes the build number instead of storing it separately in emacs-build-number.
Emacs has been ported to IRIX.
Several options and variables have been removed to simplify Emacs and potentially make it less reliable. These include the --module-assertions option, the attempt-stack-overflow-recovery variable, and the attempt-orderly-shutdown-on-fatal-signal variable.
簡略化にたいする継続要求の一環として、他の多くの関数と変数が排除されました。

Appendix B GNU Free Documentation License

Version 1.3, 3 November 2008

Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of “copyleft”, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The “Document”, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as “you”. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A “Modified Version” of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A “Secondary Section” is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document’s overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The “Invariant Sections” are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The “Cover Texts” are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A “Transparent” copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not “Transparent” is called “Opaque”.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The “Title Page” means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, “Title Page” means the text near the most prominent appearance of the work’s title, preceding the beginning of the body of the text.

The “publisher” means any person or entity that distributes copies of the Document to the public.

A section “Entitled XYZ” means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as “Acknowledgements”, “Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” of such a section when you modify the Document means that it remains a section “Entitled XYZ” according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
VERBATIM COPYING
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document’s license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
4. Preserve all the copyright notices of the Document.
5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document’s license notice.
8. Include an unaltered copy of this License.
9. Preserve the section Entitled “History”, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled “History” in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the “History” section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
11. For any section Entitled “Acknowledgements” or “Dedications”, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
13. Delete any section Entitled “Endorsements”. Such a section may not be included in the Modified Version.
14. Do not retitle any existing section to be Entitled “Endorsements” or to conflict in title with any Invariant Section.
15. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version’s license notice. These titles must be distinct from any other section titles.

You may add a section Entitled “Endorsements”, provided it contains nothing but endorsements of your Modified Version by various parties—for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
COMBINING DOCUMENTS
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled “History” in the various original documents, forming one section Entitled “History”; likewise combine any sections Entitled “Acknowledgements”, and any sections Entitled “Dedications”. You must delete all sections Entitled “Endorsements.”
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an “aggregate” if the copyright resulting from the compilation is not used to limit the legal rights of the compilation’s users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document’s Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
TRANSLATION
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled “Acknowledgements”, “Dedications”, or “History”, the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, or distribute it is void, and will automatically terminate your rights under this License.

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, receipt of a copy of some or all of the same material does not give you any rights to use it.
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See https://www.gnu.org/licenses/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License “or any later version” applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation. If the Document specifies that a proxy can decide which future versions of this License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Document.
RELICENSING
“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any World Wide Web server that publishes copyrightable works and also provides prominent facilities for anybody to edit those works. A public wiki that anybody can edit is an example of such a server. A “Massive Multiauthor Collaboration” (or “MMC”) contained in the site means any set of copyrightable works thus published on the MMC site.

“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 license published by Creative Commons Corporation, a not-for-profit corporation with a principal place of business in San Francisco, California, as well as future copyleft versions of that license published by that same organization.

“Incorporate” means to publish or republish a Document, in whole or in part, as part of another Document.

An MMC is “eligible for relicensing” if it is licensed under this License, and if all works that were first published under this License somewhere other than this MMC, and subsequently incorporated in whole or in part into the MMC, (1) had no cover texts or invariant sections, and (2) were thus incorporated prior to November 1, 2008.

The operator of an MMC Site may republish an MMC contained in the site under CC-BY-SA on the same site at any time before August 1, 2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

  Copyright (C)  year  your name.
  Permission is granted to copy, distribute and/or modify this document
  under the terms of the GNU Free Documentation License, Version 1.3
  or any later version published by the Free Software Foundation;
  with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
  Texts.  A copy of the license is included in the section entitled ``GNU
  Free Documentation License''.

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the “with…Texts.” line with this:

    with the Invariant Sections being list their titles, with
    the Front-Cover Texts being list, and with the Back-Cover Texts
    being list.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Appendix C GNU General Public License

Version 3, 29 June 2007

Copyright © 2007 Free Software Foundation, Inc. https://fsf.org/

Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.

Preamble

The GNU General Public License is a free, copyleft license for software and other kinds of works.

The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program—to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.

Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.

For the developers’ and authors’ protection, the GPL clearly explains that there is no warranty for this free software. For both users’ and authors’ sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.

Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users’ freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and modification follow.

TERMS AND CONDITIONS

Definitions.
“This License” refers to version 3 of the GNU General Public License.

“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.

“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.

To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.

A “covered work” means either the unmodified Program or a work based on the Program.

To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.

To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.

An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
Source Code.
The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.

A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.

The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.

The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work’s System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.

The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.

The Corresponding Source for a work in source code form is that same work.
Basic Permissions.
All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
Protecting Users’ Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.

When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work’s users, your or third parties’ legal rights to forbid circumvention of technological measures.
Conveying Verbatim Copies.
You may convey verbatim copies of the Program’s source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
1. The work must carry prominent notices stating that you modified it, and giving a relevant date.
2. The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
3. You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
4. If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation’s users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
1. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
2. Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
3. Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
4. Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
5. Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.

A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.

“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.

If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).

The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.

Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
Additional Terms.
“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.

When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
1. Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
2. Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
3. Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
4. Limiting the use for publicity purposes of names of licensors or authors of the material; or
5. Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
6. Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
Termination.
You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).

However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.

Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.

Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.

An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party’s predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
Patents.
A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor’s “contributor version”.

A contributor’s “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.

Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor’s essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.

In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.

If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient’s use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.

A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.

Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
No Surrender of Others’ Freedom.
If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.

If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy’s public statement of acceptance of a version permanently authorizes you to choose that version for the Program.

Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

one line to give the program's name and a brief idea of what it does.
Copyright (C) year name of author

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see https://www.gnu.org/licenses/.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:

program Copyright (C) year name of author
This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
This is free software, and you are welcome to redistribute it
under certain conditions; type ‘show c’ for details.

The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate parts of the General Public License. Of course, your program’s commands might be different; for a GUI interface, you would use an “about box”.

You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see https://www.gnu.org/licenses/.

The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read https://www.gnu.org/licenses/why-not-lgpl.html.

Appendix D ヒントと規約

このチャプターででは、Emacs Lispの追加機能については説明しません。かわりに、以前のチャプターで説明した機能を効果的に使う方法と、Emacs Lispプログラマーがしたがうべき慣習を説明します。

You can automatically check some of the conventions described below by running the command M-x checkdoc RET when visiting a Lisp file. It cannot check all of the conventions, and not all the warnings it gives necessarily correspond to problems, but it is worth examining them all. Alternatively, use the command M-x checkdoc-current-buffer RET to check the conventions in the current buffer, or checkdoc-file when you want to check a file in batch mode, e.g., with a command run by M-x compile RET.

D.1 Emacs Lispコーディングの慣習		明快で堅牢なプログラムにたいする慣習。
D.2 キーバインディングの慣習		どのキーをどのプログラムにバインドすべきか。
D.3 Emacsプログラミングのヒント		Emacsコードを円滑にEmacsに適合させる。
D.4 コンパイル済みコードを高速化ためのヒント		コンパイル済みコードの実行を高速にする。
D.5 コンパイラー警告を回避するためのヒント		コンパイラー警告をオフにする。
D.6 ドキュメント文字列のヒント		読みやすいドキュメント文字列の記述。
D.7 コメント記述のヒント		コメント記述の慣習。
D.8 Emacsライブラリーのヘッダーの慣習		ライブラリーパッケージにたいする標準的なヘッダー。

D.1 Emacs Lispコーディングの慣習

以下は、幅広いユーザーを意図したEmacs Lispコードを記述する際にしたがうべき慣習です:

単なるパッケージのロードが、Emacsの編集の挙動を変更すねきではない。コマンドと、その機能を有効または無効にするコマンド、またはそれの呼び出しが含まれる。
この慣習は、カスタム定義を含むすべてのファイルに必須である。そのようなファイルを、この慣習にしたがうために修正するのが、非互換の変更を要求するなら、構うことはないから、非互換の修正を行うこと。先送りにしてはならない。
他のLispプログラムと区別するための、短い単語を選択すること。あなたのプログラム内のグローバルなシンボルすべて、すなわち変数、定数、関数の名前はその選択したプレフィクスで始まること。そのプレフィクスと名前の残りの部分は、ハイフン‘-’で区切る。Emacs Lisp内のすべてのグローバル変数は同じネームスペース、関数はすべて別のネームスペースを共有するので、これの実践は名前の競合を回避する²¹。他のパッケージから使用されることを意図しない場合には、プレフィクス名前を2つのハイフンで区切ること。
Occasionally, for a command name intended for users to use, it is more convenient if some words come before the package’s name prefix. For example, it is our convention to have commands that list objects named as ‘list-something’, e.g., a package called ‘frob’ could have a command ‘list-frobs’, when its other global symbols begin with ‘frob-’. Also, constructs that define functions, variables, etc., work better if they start with ‘defun’ or ‘defvar’, so put the name prefix later on in the name.

この勧告は、copy-listのようなEmacs Lisp内のプリミティブではなく、伝統的なLispプリミティブにさえ適用される。信じようと信じまいと、copy-listを定義する尤もらしい方法は複数あるのだ。安全第一である。かわりにfoo-copy-listやmylib-copy-listのような名前を生成するために、あなたの名前プレフィクスを追加しよう。

twiddle-filesのような特定の名前でEmacsに追加されるべきと考えている関数を記述する場合には、プログラム内でそれを名前で呼び出さないこと。プログラム内ではそれをmylib-twiddle-filesで呼び出して、わたしたちがそれをEmacsに追加するため提案メールを、‘bug-gnu-emacs@gnu.org’に送信すること。もし追加することになったそのとき、わたしたちは十分容易にその名前を変更できるだろう。

1つのプレフィクスで十分でなければ、それらに意味があるかぎり、あなたんパッケージは2つまたは3つの一般的なプレフィクス候補を使用できる。
個々のLispファイルすべての終端に、provide呼出を配置すること。名前つき機能を参照されたい。
事前に他の特定のLispプログラムのロードを要するファイルは、そのファイル先頭のコメントでそのように告げるべきである。また、それらが確実にロードされるよう、requireを使用すること。名前つき機能を参照されたい。
ファイルfooが、別のファイルbar内で定義されたマクロを使用するが、bar内の他の関数や変数を何も使用しない場合には、fooに以下の式を含めるべきである:
```
(eval-when-compile (require 'bar))
```
これは、fooのバイトコンパイル直前にbarをロードするようEmacsに告げるので、そのマクロはコンパイル中は利用可能になる。eval-when-compileの使用により、コンパイル済みバージョンのfooが中古なら、barのロードを避けられる。これはファイル内の、最初のマクロ呼び出しの前に呼び出すこと。マクロとバイトコンパイルを参照されたい。
実行時、それらが本当に必要でなければ、追加ライブラリーのロードを避けること。あなたのファイルが、単に他のいくつかのライブラリーなしでは機能しないなら、単にトップレベルでそのライブラリーをrequireして、それを使って行うこと。しかしあなたのファイルが、いくつかの独立した機能を含み、それらの1つか2つだけが余分なライブラリーを要するなら、トップレベルではなく関連する関数内部に、requireを配置することを考慮すること。または必要時に余分のライブラリーをロードするために、autoloadステートメントを使用すること。この方法では、あなたのファイルの該当部分を使用しない人は、余分なライブラリーをロードする必要がなくなる。
Common Lisp拡張が必要なら、古いclライブラリーではなく、cl-libライブラリーを使うこと。clライブラリーは、クリーンなネームスペースを使用しない(定義が‘cl-’で始まらない)。パッケージが実行時にclをロードする場合、そのパッケージを使用しないユーザーにたいして、名前の衝突を起こすかもしれない。
(eval-when-compile (require 'cl))で、コンパイル時にclを使用するのは問題ない。コンパイラーはバイトコードを生成する前にマクロを展開するので、cl内のマクロを使用するには十分である。ただしこの場合でも、現代的なcl-libを使用したほうが良い。
メジャーモードを定義する際には、メジャーモードの慣習にしたがってほしい。メジャーモードの慣習を参照されたい。
マイナーモードを定義する際には、マイナーモードの慣習にしたがってほしい。マイナーモード記述の規約を参照されたい。
ある関数の目的が、特定の条件の真偽を告げることであるなら、(述語である“predicate”を意味する)‘p’で終わる名前を与えること。その名前が1単語なら単に‘p’を追加し、複数単語なら‘-p’を追加する。例はframepやframe-live-p。
ある変数の目的が、単一の関数の格納にあるなら、‘-function’で終わる名前を与えること。ある変数の目的が、関数のリストの格納にあるなら(たとえばその変数がフックなら)、フックの命名規約にしたがってほしい。フックを参照されたい。
If loading the file adds functions to hooks, define a function feature-unload-function, where feature is the name of the feature the package provides, and make it undo any such changes. Using unload-feature to unload the file will run this function. See section アンロード.
Emacsのプリミティブにエイリアスを定義するのは、悪いアイデアである。通常は、かわりに標準の名前を使用すること。エイリアスが有用になるかもしれないケースは、後方互換性や可搬性を向上させる場合である。
パッケージで、別のバージョンのEmacsにたいする互換性のためにエイリアスや新たな関数の定義が必要なら、別のバージョンにあるそのままの名前ではなく、そのパッケージのプレフィクスを名前に付加すること。以下は、そのような互換性問題を多く提供するGnusでの例である。
```
(defalias 'gnus-point-at-bol
  (if (fboundp 'point-at-bol)
      'point-at-bol
    'line-beginning-position))
```
Emacsのプリミティブの再定義やadviseは悪いアイデアである。これは特定のプログラムには正しいことを行うが、結果として他のプロラムが破壊されるかもしれない。
同様に、あるLispパッケージで別のLispパッケージ内の関数にadviseするのも悪いアイデアである。
Avoid using eval-after-load and with-eval-after-load in libraries and packages (see section ロードのためのフック). This feature is meant for personal customizations; using it in a Lisp program is unclean, because it modifies the behavior of another Lisp file in a way that’s not visible in that file. This is an obstacle for debugging, much like advising a function in the other package.
Emacsの標準的な関数やライブラリープログラムの何かをファイルが置換するなら、そのファイル冒頭の主要コメントで、どの関数が置換されるか、および置換によりオリジナルと挙動がどのように異なるかを告げること。
関数や変数を定義するコンストラクターは、関数ではなくマクロであるべきで、その名前は‘define-’で始まること。そのマクロは、定義される名前を1つ目の引数で受け取ること。これは自動的に定義を探す、種々のツールを助けることになる。マクロ自身の中でその名前を構築するのは、それらのツールを混乱させるので避けること。
別のいくつかのシステムでは、‘*’が先頭や終端にある変数名を選択する慣習がある。Emacs Lispではその慣習を使用しないので、あなたのプログラム内でそれを使用しないでほしい。(Emacsでは特別な目的をもつバッファーだけに、そのような名前を使用する)。すべてのライブラリーが同じ慣習を使用するなら、人はEmacsがより整合性があることを見い出すだろう。
Emacs LispソースファイルのデフォルトのファイルコーディングシステムはUTFである(テキストの表現方法を参照)。あなたのプログラムがUTF-8以外の文字を含むような稀なケースでは、ソースファイル内の‘-*-’行かローカル変数リスト内で、適切なコーディングシステムを指定するべきである。Local Variables in Files in The GNU Emacs Manualを参照されたい。
デフォルトのインデントパラメーターで、ファイルをインデントすること。
自分で行に閉カッコを配置するのを習慣としてはならない。Lispプログラマーは、これに当惑させられる。
コピーを配布する場合は著作権表示と複製許可表示を配してほしい。Emacsライブラリーのヘッダーの慣習を参照されたい。

D.2 キーバインディングの慣習

Dired、Info、Compilation、Occurなどの多くのメジャーモードでは、ハイパーリンクを含むを読み取り専用テキストとして処理するようデザインされている。そのようなメジャーモードは、リンクをフォローするようmouse-2とRETを再定義すること。そのリンクがmouse-1-click-follows-linkにしたがうよう、follow-link条件もセットアップすること。クリック可能なテキストの定義を参照されたい。そのようなクリック可能リンクを実装する簡便な手法については、ボタンを参照されたい。
Lispプログラム内のキーとして、C-c letterを定義してはならない。C-cとアルファベット(大文字と小文字の両方)からなるシーケンスは、ユーザー用に予約済みである。これらはユーザー用に、唯一予約されたシーケンスなので、それを阻害してはならない。
すべてのメジャーモードがこの慣習を尊重するよう変更するには、多大な作業を要する。この慣習を捨て去れば、そのような作業は不要になり、ユーザーは不便になるだろう。この慣習を遵守してほしい。
修飾キーなしのF5からF9までのファンクションキーも、ユーザー定義用に予約済みである。
後にコントロールキーか数字が続くC-cシーケンスは、メジャーモード用に予約済みである。
後に{、}、<、>、 :、;が続くC-cシーケンスも、メジャーモード用に予約済みである。
Sequences consisting of C-c followed by any other ASCII punctuation or symbol character are allocated for minor modes. Using them in a major mode is not absolutely prohibited, but if you do that, the major mode binding may be shadowed from time to time by minor modes.
後にプレフィクス文字(C-cを含む)が続くC-hをバインドしてはならない。C-hをバインドしなければ、そのプレフィクス文字をもつサブコマンドをリストするためのヘルプ文字として、それが自動的に利用可能になる。
別のESCが後に続く場合を除き、ESCで終わるキーシーケンスをバインドしてはならない(つまりESC ESCで終わるキーシーケンスのバインドはOK)。
このルールの理由は、任意のンテキストでの非プレフィクスであるようなESCのバインディングは、そのコンテキストにおいてファンクションキーとなるようなエスケープシーケンスの認識を阻害するからである。
Similarly, don’t bind a key sequence ending in C-g, since that is commonly used to cancel a key sequence.
一時的なモードや、ユーザーが出入り可能な状態のような動作はすべて、エスケープ手段としてESC ESCかESC ESC ESCを定義すること。
通常のEmacsコマンドを受け入れる状態、より一般的には後にファンクションキーか矢印キーが続くESC内のような状態は潜在的な意味をもつので、ESC ESCを定義してはならない。なぜならそれは、ESCの後のエスケープシーケンスの認識を阻害するからである。これらの状態においては、エスケープ手段としてESC ESC ESCを定義すること。それ以外なら、かわりにESC ESCを定義すること。

D.3 Emacsプログラミングのヒント

以下の慣習にしたがうことにより実行時、あなたのプログラムがよりEmacsに適合するようになります。

プログラム内でnext-lineやprevious-lineを使用してはならない。ほとんど常に、forward-lineのほうがより簡便で、より予測可能かつ堅牢である。テキスト行単位の移動を参照のこと。
あなたのプログラム内で、マークのセットが意図した機能でないなら、マークをセットする関数を呼び出してはならない。マークはユーザーレベルの機能なので、ユーザーの益となる値を提供する場合を除き、マークの変更は間違っている。マークを参照のこと。
得に、以下の関数は使用しないこと:
- beginning-of-buffer、end-of-buffer
- replace-string、replace-regexp
- insert-file、insert-buffer
インタラクティブなユーザーを意図した別の機能がないのにポイントの移動、特定の文字列の置換、またはファイルやバッファーのコンテンツを挿入したいだけなら、単純な1、2行のLispコードでそれらの関数を置き換えられる。
ベクターを使用する特別な理由がある場合を除き、ベクターではなくリストを使用すること。Lispでは、ベクターよりリストを操作する機能のほうが多く、リストを処理するほうが通常は簡便である。
要素の挿入や削除がなく(これはリストだけで可能)、ある程度のサイズがあって、(先頭か末尾から検索しない)ランダムアクセスがあるテーブルでは、ベクターが有利である。
エコーエリア内にメッセージを表示する推奨方法は、princではなくmessage関数である。エコーエリアを参照のこと。
エラーコンディションに遭遇したときは、関数error(またはsignal)を呼び出すこと。関数errorはリターンしない。エラーをシグナルする方法を参照のこと。
エラーの報告にmessage、throw、sleep-for、beepを使用しないこと。
エラーメッセージは大文字で始まり、ピリオドで終わらないこと。
ミニバッファー内でyes-or-no-pかy-or-n-pで答えを求める質問を行う場合には、大文字で始めて‘?’で終わること。
ミニバッファーのプロンプトでデフォルト値を示すときは、カッコ内に単語‘default’を配すること。これは以下のようになる:
```
Enter the answer (default 42):
```
In interactive, if you use a Lisp expression to produce a list of arguments, don’t try to provide the correct default values for region or position arguments. Instead, provide nil for those arguments if they were not specified, and have the function body compute the default value when the argument is nil. For instance, write this:
```
(defun foo (pos)
  (interactive
   (list (if specified specified-pos)))
  (unless pos (setq pos default-pos))
  ...)
```
以下のようにはしないよう:
```
(defun foo (pos)
  (interactive
   (list (if specified specified-pos
             default-pos)))
  ...)
```
これは、そのコマンドを繰り返す場合に、そのときの状況にもとづいてデフォルト値が再計算されるからである。

interactiveの‘d’、‘m’、‘r’指定を使用する際、これらはコマンドを繰り返すときの引数値の再計算にたいして特別な段取りを行うので、このような注意事項を採用する必要はない。
実行に長時間を要する多くのコマンドは、開始時に‘Operating...’、完了時に‘Operating...done’のような、何らかのメッセージを表示すること。これらのメッセージのスタイルは、‘...’の周囲にスペースを置かず、‘done’の後にピリオドを置かないよう、一定に保ってほしい。そのようなメッセージを生成する簡便な方法は、処理の進捗レポートを参照のこと。
再帰編集の使用を避けること。かわりにRmailのeコマンドが行うように、元のローカルキーマップに戻るよう定義したコマンドを含む、新たなローカルキーマップを使用する。または単に別のバッファーにスイッチして、ユーザーが自身で戻れるようにすること。再帰編集を参照っされたい。

D.4 コンパイル済みコードを高速化ためのヒント

以下は、バイトコンパイル済みLispプログラムの実行速度を改善する方法です。

その時間がどこで消費されているか見つかるために、プログラムのプロファイルを行う。プロファイリングを参照のこと。
可能なら常に再帰ではなく繰り返しを使用する。Emacs Lispでは、コンパイル済み関数が別のコンパイル済み関数を呼び出すときでさえ、関数呼び出しは低速である
プリミティブのリスト検索関数memq、member、assq、assocは明示的な繰り返しより更に高速である。これらの検索プリミティブを使用できるように、データ構造を再配置することにも価値が有り得る。
特定のビルトイン関数は、通常の関数呼び出しの必要を回避するよう、バイトコンパイル済みコードでは特別に扱われる。別の候補案のかわりにこれらの関数を使用するのは、良いアイデアである。コンパイラーにより特別に扱われる関数かどうかを確認するには、それのbyte-compileプロパティを調べればよい。そのプロパティが非nilなら、その関数は特別に扱われる。
たとえば以下を入力すると、arefが特別にコンパイルされえることが示される(配列を操作する関数を参照):
```
(get 'aref 'byte-compile)
     ⇒ byte-compile-two-args
```
この場合(および他の多くの場合)、最初にbyte-compileプロパティを定義する、bytecompライブラリーをロードしなければならない。
プログラム内で実行時間のある程度を占める小さい関数を呼び出すなら、その関数をinlineにする。これにより、関数呼び出しのオーバーヘッドがなくなる。関数のinline化はプログラム変更の自由度を減少させるので、ユーザーがスピードを気にするに足るほど低速であり、inline化により顕著に速度が改善されるのでなければ、これを行ってはならない。インライン関数Inline Functionsを参照のこと。

D.5 コンパイラー警告を回避するためのヒント

以下のように、ダミーのdefvar定義を追加して、未定義のフリー変数に関する、コンパイラーの警告の回避を試みる:
```
(defvar foo)
```
このような定義は、そのファイル内での変数fooの使用にたいして、コンパイラーが警告すないようにする以外、影響はない。
同様にdeclare-functionステートメントを使用して、定義されるこが既知の未定義関数に関する、コンパイラーの警告の回避を試みる(コンパイラーへの定義済み関数の指示を参照)。
If you use many functions, macros, and variables from a certain file, you can add a require (see section require) for that package to avoid compilation warnings for them, like this:
```
(require 'foo)
```
If you need only macros from some file, you can require it only at compile time (see section コンパイル中の評価). For instance,
```
(eval-when-compile
  (require 'foo))
```
ある関数内で変数をバインドして、別の関数内でそれを使用またはセットする場合、その変数が定義をもたなければ、その別関数に関してコンパイラーは警告を行う。しかしその変数が短い名前をもつ場合、Lispパッケージは短い変数名を定義するべきではないので、定義の追加により不明瞭になるかもしれない。行うべき正しい方法は、パッケージ内の他の関数や変数に使用されている名前プレフィクスで始まるよう、その変数をリネームすることである。
警告を回避する最後の手段は、通常なら間違いであるが、その使用法では間違いではないと解っている何かを行う際には、それをwith-no-warningsの内側に置くこと。コンパイラーのエラーを参照されたい。

D.6 ドキュメント文字列のヒント

以下は、ドキュメント文字列記述に関するいくつかのヒントと慣習です。コマンドM-x checkdoc-minor-modeを実行すれば、これらの慣習の多くをチェックできます。

ユーザーが理解することを意図したすべての関数、コマン、変数はドキュント文字列をもつこと。
Lispプログラムの内部的な変数とサブルーチンは、同様にドキュメント文字列をもつことができる。ドキュメント文字列は、実行中のEmacs内で非常に僅かなスペースしか占めない。
80列スクリーンのEmacsウィンドウに適合するように、ドキュメント文字列をフォーマットすること。ほとんどの行を60文字以下に短くするのは、良いアイデアである。最初の行は67文字以下にすること。さもないとaproposの出力で見栄えが悪くなる。
見栄えがよくなるなら、そのテキストをフィルできる。Emacs Lispモードは、emacs-lisp-docstring-fill-columnで指定された幅に、ドキュメント文字列をフィルする。しかし、ドキュメント文字列の行ブレークを注意深く調整すれば、ドキュメント文字列の可読性をより向上できることがある。ドキュメント文字列が長い場合には、セクション間に空行を使用すること。
ドキュンメント文字列の最初の行は、それ自身が要約となるような、1つか2つの完全なセンテンスから成り立つこと。M-x aproposは最初の行だけを表示するので、その行のコンテンツが自身で完結していなければ、結果の見栄えは悪くなる。特に、最初の行は大文字で始めて、ピリオで終わること。
関数では最初の行は“その関数は何を行うのか?”、変数にたいしては最初の行は“その値は何を意味するのか?”という問いに簡略に答えること。

ドキュメント文字列を1行に制限しないこと。その関数や変数の使用法の詳細を説明する必要に応じて、その分の行数を使用すること。テキストの残りの部分にたいしても、完全なセンテンスを使用してほしい。
ユーザーが無効化されたコマンドの使用を試みる際、Emacsはそれのドキュメント文字列の最初のパラグラフ(最初の空行までのすべて)だけを表示する。もし望むならえ、その表示をより有用になるよう、最初の空行の前に何の情報を含めるか選択できる。
最初の行では、その関数のすべての重要な引数と、関数呼び出しで記述される順に、それらに言及すること。その関数が多くの引数をもつなら、最初の行でそれらすべてに言及するのは不可能である。この場合、もっとも重要な引数を含む、最初の引数数個について最初の行で言及すること。
ある関数のドキュメント文字列がその関数の引数の値に言及する際には、引数を大文字にした名前が引数の値であるかのように使用すること。つまり関数evalのドキュメント文字列では、最初の引数の名前がformなので、‘FORM’で参照する:
```
Evaluate FORM and return its value.
```
同様に、リストやベクターをサブユニットへの分解で、それらのいくつかを異なるように示すような際には、メタ構文変数(metasyntactic variables)を大文字で記述すること。以下の例の‘KEY’と‘VALUE’は、これの実践例である:
```
The argument TABLE should be an alist whose elements
have the form (KEY . VALUE).  Here, KEY is ...
```
ドキュメント文字列内でLispシンボルに言及する際は、大文字小文字を絶対に変更しないこと。そのシンボルの名前がfooなら、“Foo”ではなく“foo”である(“Foo”は違うシンボルだ)。
これは、関数の引数の値の記述ポリシーと反するように見えるかもしれないが、矛盾は実際には存在しない。引数のvalueは、その関数が値の保持に使用するsymbolと同じではない。

これによりセンテンス先頭に小文字を置くことになり、それが煩しいなら、センテンス開始がシンボルにならないようそのセンテンスを書き換えること。
ドキュメント文字列の開始と終了は空白文字を使用しないこと。
ソースコード内の後続行のテキストが、最初の行と揃うとうに、ドキュメント文字列の後続行をインデントしてはならない。これはソースコードでは見栄えがよいが、ユーザーがドキュメトを閲覧する際は奇妙な見栄えになる。開始のダブルクォーテーションの前のインデントは、その文字列の一部には含まれないことを忘れないこと!
When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), surrounding it with curved single quotes (‘ and ’). There are two exceptions: write t and nil without surrounding punctuation. For example: ‘CODE can be ‘lambda’, nil, or t’. See Quotation Marks in The GNU Emacs Manual, for how to enter curved single quotes.
Documentation strings can also use an older single-quoting convention, which quotes symbols with grave accent ` and apostrophe ': `like-this' rather than ‘like-this’. This older convention was designed for now-obsolete displays in which grave accent and apostrophe were mirror images. Documentation using this convention is converted to the user’s preferred format when it is copied into a help buffer. See section ドキュメント内でのキーバインディングの置き換え.

Help mode automatically creates a hyperlink when a documentation string uses a single-quoted symbol name, if the symbol has either a function or a variable definition. You do not need to do anything special to make use of this feature. However, when a symbol has both a function definition and a variable definition, and you want to refer to just one of them, you can specify which one by writing one of the words ‘variable’, ‘option’, ‘function’, or ‘command’, immediately before the symbol name. (Case makes no difference in recognizing these indicator words.) For example, if you write
```
This function sets the variable `buffer-file-name'.
```
これのハイパーリンクはbuffer-file-nameの変数のドキュメントだけを参照し、関数のドキュメントは参照しない。

あるシンボルが関数、および/または変数の定義をもつが、ドキュメントしているシンボルの使用とそれらが無関係なら、すべてのハイパーリンク作成を防ぐために、そのシンボル名の前に単語‘symbol’か‘program’を記述できる。たとえば、
```
If the argument KIND-OF-RESULT is the symbol `list',
this function returns a list of all the objects
that satisfy the criterion.
```
これは、ここでは無関係な関数listのドキュメントに、ハイパーリンクを作成しない。

通常、変数ドキュメントがない変数には、ハイパーリンクは作成されない。そのような変数の前に単語‘variable’と‘option’のいずれかを記述すれば、ハイパーリンクの作成を強制できる。

フェイスにたいするハイパーリンクは、そのフェイスの前か後に単語‘face’があれば作成される。この場合には、たとえそのシンボルが変数や関数として定義されていても、フェイスのドキュメントだけが表示される。

To make a hyperlink to Info documentation, write the single-quoted name of the Info node (or anchor), preceded by ‘info node’, ‘Info node’, ‘info anchor’ or ‘Info anchor’. The Info file name defaults to ‘emacs’. For example,
```
See Info node `Font Lock' and Info node `(elisp)Font Lock Basics'.
```
Finally, to create a hyperlink to URLs, write the single-quoted URL, preceded by ‘URL’. For example,
```
The home page for the GNU project has more information (see URL
`https://www.gnu.org/').
```
ドキュメント文字列内に直接キーシーケンスを記述しないこと。かわりに、それらを表すために‘\\[…]’構造を使用すること。たとえば‘C-f’と記述するかわりに、‘\\[forward-char]’と記述する。Emacsがドキュメント文字列を表示する際には、何であれカレントでforward-charにバインドされたキーに置き換える(これは通常は‘C-f’だが、そのユーザーがキーバインディングを移動していれば、何か他の文字かもしれない)。ドキュメント内でのキーバインディングの置き換えを参照のこと。
メジャーモードのドキュメント文字列では、グローバルマップではなく、そのモードのローカルマップを参照したいだろう。したがって、どのキーマップを使用するか指定するために、ドキュメント文字列内で一度‘\\<…>’構造を使用する。最初に‘\\[…]’を使用する前にこれを行うこと。‘\\<…>’の内部のテキストは、そのメジャーモードにたいするローカルキーマップを含む変数名であること。
ドキュメント文字列の表示が低速になるので、非常に多数回の‘\\[…]’の使用は実用的ではない。メジャーモードのもっとも重要なコマンドの記述にこれを使用し、そのモードの残りのキーマップの表示には‘\\{…}’を使用する。
一貫性を保つために,関数のドキュメント文字列の最初のセンテンス内の動詞は、命令形で表すこと。たとえば“Return the cons of A and B.”か、好みによっては“Returns the cons of A and B.”を使用する。通常は、最初のパラグラフの残りの部分にたいして、同様に行っても見栄えがよい。各センテンスが叙実的で適切な主題をもつなら、後続のパラグラフの見栄えはよくなる。
The documentation string for a function that is a yes-or-no predicate should start with words such as “Return t if”, to indicate explicitly what constitutes truth. The word “return” avoids starting the sentence with lower-case “t”, which could be somewhat distracting.
ドキュメント文字列内の開カッコで始まる行は、以下のように開カッコの前にバックスラッシュを記述する:
```
The argument FOO can be either a number
\(a buffer position) or a string (a file name).
```
これはその開カッコがdefunの開始として扱われることを防ぐ(Defuns in The GNU Emacs Manualを参照)。
ドキュメント文字列は受動態ではなく能動態、未来形ではなく現在形で記述すること。たとえば、“A list containing A and B will be returned.”ではなく、“Return a list containing A and B.”と記述すること。
不必要な“cause”(および同等の単語)の使用を避けること。“Cause Emacs to display text in boldface”ではなく、単に“Display text in boldface”と記述すること。
多くの人にとってなじみがなく、それをtypoと間違えるであろうから、“iff”(“if and only if”を意味する数学用語)の使用を避けること。ほとんどの場合、その意味は単なる“if”で明快である。それ以外では、その意味を伝える代替えフレーズを探すよう試みること。
特定のモードや状況でのみコマンドに意味がある際には、ドキュメント文字列内でそれに言及すること。たとえばdired-find-fileのドキュメントは:
```
In Dired, visit the file or directory named on this line.
```
ユーザーがセットしたいと望むかもしれないオプションを表す変数を定義する際には、defcustomを使用すること。グローバル変数の定義を参照されたい。
yes-or-noフレアグであるような変数のドキュメント文字列は、すべての非nil値が等価であることを明確にし、nilと非nilが何を意味するかを明示的に示すために、“Non-nil means”のような単語で始めること。

D.7 コメント記述のヒント

コメントにたいして、以下の慣習を推奨します:

‘;’

1つのセミコロン‘;’で始まるコメントは、すべてソースコードの右側の同じ列に揃えられる。そのようなコメントは通常、その行のコードがどのように処理を行うかを説明する。たとえば:

(setq base-version-list                 ; There was a base
      (assoc (substring fn 0 start-vn)  ; version to which
             file-version-assoc-list))  ; this looks like
                                        ; a subversion.

‘;;’

2つのセミコロン‘;;’で始まるコメントは、コードと同じインデントレベルで揃えられる。そのようなコメントは通常、その後の行の目的や、その箇所でのプログラムの状態を説明する。たとえば:

(prog1 (setq auto-fill-function
             …
             …
  ;; Update mode line.
  (force-mode-line-update)))

わたしたちは、通常は関数の外側のコメントにも2つのセミコロンを使用する。

;; This Lisp code is run in Emacs when it is to operate as
;; a server for other processes.

関数がドキュメント文字列をもたなければ、かわりにその関数の直前にその関数が何を行うかと、正しく呼び出す方法を説明する、2つのセミコロンのコメントをもつべきである。各引数の意味と、引数で可能な値をその関数が解釈する方法を、しっかり説明すること。しかし、そのようなコメントはドキュメント文字列に変換するほうが、はるかに優れている。

‘;;;’

Comments that start with three semicolons, ‘;;;’, should start at the left margin. We use them for comments which should be considered a heading by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, comments starting with two or fewer are not. Historically, triple-semicolon comments have also been used for commenting out lines within a function, but this use is discouraged.

関数全体をコメントアウトするときは、2つのセミコロンを使用する。

‘;;;;’

4つのセミコロン‘;;;;’で始まるコメントは左マージンに揃えられ、プログラムのメジャーセクションのheadingに使用される。たとえば:

;;;; The kill ring

一般的に言うと、コマンドM-; (comment-dwim)は、適切なタイプのコメントを自動的に開始するか、セミコロンの数に応じて、既存のコメントを正しい位置にインデントします。Manipulating Comments in The GNU Emacs Manualを参照してください。

D.8 Emacsライブラリーのヘッダーの慣習

Emacsには、セクションに分割して、それの記述者のような情報を与えるために、Lispライブラリー内で特別なコメントを使用する慣習があります。それらのアイテムにたいして標準的なフォーマットを使用すれば、ツール(や人)か関連する情報を抽出するのが簡単になります。このセクションでは、以下の例を出発点にこれらの慣習を説明します。

;;; foo.el --- Support for the Foo programming language

;; Copyright (C) 2010-2018 Your Name


;; Author: Your Name <yourname@example.com>
;; Maintainer: Someone Else <someone@example.com>
;; Created: 14 Jul 2010

;; Keywords: languages
;; Homepage: http://example.com/foo

;; This file is not part of GNU Emacs.

;; This file is free software…
…
;; along with this file.  If not, see <https://www.gnu.org/licenses/>.

一番最初の行は、以下のフォーマットをもつべきです:

;;; filename --- description

この説明は1行に収まる必要があります。そのファイルに‘-*-’指定が必要なら、descriptionの後に配置してください。これにより最初の行が長くなりすぎるようなら、そのファイル終端でLocal Variablesセクションを使用してください。

The copyright notice usually lists your name (if you wrote the file). If you have an employer who claims copyright on your work, you might need to list them instead. Do not say that the copyright holder is the Free Software Foundation (or that the file is part of GNU Emacs) unless your file has been accepted into the Emacs distribution. For more information on the form of copyright and license notices, see the guide on the GNU website.

著作権表示の後は、それぞれが‘;; header-name:’で始まる、複数のヘッダーコメント(header comment)を記述します。以下は、慣習的に利用できるheader-nameのテーブルです:

‘Author’

この行は、その少なくともライブラリーの主要な作者の、名前とemailアドレスを示す。複数の作者がいる場合は、前に;;とタブか少なくとも2つのスペースがある継続行で、彼らをリストする。わたしたちは、‘<…>’という形式で連絡用emailアドレスを含めることを推奨する。たとえば:

;; Author: Your Name <yourname@example.com>
;;      Someone Else <someone@example.com>
;;      Another Person <another@example.com>

‘Maintainer’

このヘッダーは、Authorヘッダーと同じフォーマットである。これは、現在そのファイルを保守(バグレポートへの応答等)をする人(か人々)をリストする。

Maintainerの行がなければ、Authorフィールドの人(人々)が、Maintainerとみなされる。Emacs内のいくつかのファイルは、Maintainerに‘FSF’を使用している。これは、そのファイルにたいしてオリジナル作者がもはや責任をもっておらず、Emacsの一部として保守されていることを意味する。

‘Created’

このオプションの行は、そのファイルのオリジナルの作成日付を与えるもので、歴史的な興味のためだけにある。

‘Version’

個々のLispプログラムにたいしてバージョン番号を記録したいなら、この行に配置する。Emacsとともに配布されたLispファイルは、Emacsのバージョン番号自体が同じ役割を果たすので、一般的には‘Version’ヘッダーをもたない。複数ファイルのコレクションを配布する場合には、各ファイルではなく、主となるファイルにバージョンを記述することを推奨する。

‘Keywords’

This line lists keywords for the finder-by-keyword help command. Please use that command to see a list of the meaningful keywords. The command M-x checkdoc-package-keywords RET will find and display any keywords that are not in finder-known-keywords. If you set the variable checkdoc-package-keywords-flag non-nil, checkdoc commands will include the keyword verification in its checks.

このフィールドは、トピックでパッケージを探す人が、あなたのパッケージを見つける手段となる。キーワードを分割するには、スペースとカンマの両方を使用できる。

人はしばしばこのフィールドを、単にFinder(訳注: finder-by-keywordがオープンするバッファー)に関連したキーワードではなく、そのパッケージを説明する任意のキーワードを記述する箇所だとみなすのは不運なことである。

‘Homepage’

‘URL’

These lines state the homepage of the library.

‘Package-Version’

‘Version’がパッケージマネージャーによる使用に適切でなければ、パッケージは‘Package-Version’を定義できる。かわりにこれが使用される。これは‘Version’がRCSやversion-to-listでパース不能な何かであるようなら、これが手軽である。パッケージ化の基礎を参照のこと。

‘Package-Requires’

これが存在する場合には、カレントパッケージが正しく動作するために依存するパッケージを示す。パッケージ化の基礎を参照のこと。これは(パッケージの完全なセットがダウンロードされることを確実にするために)ダウンロード時と、(すべての依存パッケージがあるときだけパッケージがアクティブになることを確実にするために)アクティブ化の両方で、パッケージマネージャーにより使用される。

Its format is a list of lists on a single line. The car of each sub-list is the name of a package, as a symbol. The cadr of each sub-list is the minimum acceptable version number, as a string that can be parse by version-to-list. An entry that lacks a version (i.e., an entry which is just a symbol, or a sub-list of one element) is equivalent to entry with version "0". For instance:

;; Package-Requires: ((gnus "1.0") (bubbles "2.7.2") cl-lib (seq))

パッケージのコードは自動的に、実行中のEmacsのカレントのバージョン番号をもつ、‘emacs’という名前のパッケージを定義する。これは、パッケージが要求するEmacsの最小のバージョンに使用できる。

ほぼすべてのLispライブラリーは、‘Author’と‘Keywords’のヘッダーコメント行をもつべきです。適切なら、他のものを使用してください。ヘッダー行内で、別のヘッダー行の名前も使用できます。これらは標準的な意味をもたないので、害になることを行うことはできません。

わたしたちは、ライブラリーファイルのコンテンツを分割するために、追加の提携コメントを使用します。これらは空行で他のものと分離されている必要があります。以下はそれらのテーブルです:

‘;;; Commentary:’: これは、そのライブラリーが機能する方法を説明する、概論コメントを開始する。これは複製許諾の直後にあり‘Change Log’、‘History’、‘Code’のコメント行で終端されていること。このテキストはFinderパッケージで使用されるので、そのコンテキスト内で有意であること。
‘;;; Change Log:’: これは、時間とともにそのファイルに加えられた、オプションの変更ロクを開始する。このセクションに過剰な情報を配してはならない。(Emacsが行うように)バージョンコントロールシステムの詳細ログや、個別のChangeLogファイルに留めるほうがよい。‘History’は、‘Change Log’の代替えである。
‘;;; Code:’: これは、そのプログラムの実際のコードを開始する。
‘;;; filename ends here’: これはフッター行(footer line)である。これはそのファイルの終端にある。これの目的は、フッター行の欠落から、人がファイルの切り詰められたバージョンを検知することを可能にする。

Appendix E GNU Emacsの内部

このチャプターでは、実行可能なEmacs実行可能形式を事前ロードされたLispライブラリーとともにダンプする方法と、ストレージが割り当てられる方法、およびCプログラマーが興味をもつかもしれないGNU Emacsの内部的な側面のいくつかを説明します。

E.1 Emacsのビルド		ダンプ済みEmacsの作成方法。
E.2 純粋ストレージ		その場かぎりの事前ロードされたLisp関数を共有する。
E.3 ガーベージコレクション		Lispオブジェクトの使用されないスペースの回収。
E.4 Stack-allocated Objects		Temporary conses and strings on C stack.
E.5 メモリー使用量		これまでに作成されたLispオブジェクトの総サイズの情報。
E.6 C方言		Emacsを記述するC系言語は何か。
E.7 Emacsプリミティブの記述		Emacs用にCコードを記述する。
E.8 オブジェクトの内部		バッファー、ウィンドウ、プロセスのデーラフォーマット。
E.9 Cの整数型		Emacs内部でCの整数型が使用される方法。

E.1 Emacsのビルド

このセクションでは、Emacs実行可能形式のビルドに関するステップの説明をします。makefileがこれらすべてを自動的に行うので、Emacsをビイルドおよびインストールするために、この題材を知る必要はありません。この情報は、Emacs開発者にとって適切です。

Building Emacs requires GNU Make version 3.81 or later.

srcディレクトリー内のCソースファイルをコンパイルすることにより、temacsと呼ばれる実行可能形式ファイルが生成されます。これはbare impure Emacs()裸で不純なEmacsとも呼ばれます。これにはEmacs LispインタープリターとI/Oルーチンが含まれますが、編集コマンドは含まれません。

コマンドtemacs -l loadupはtemacsを実行して、それがloadup.elをロードするよう計らいます。loadupライブラリーは、通常のEmacs編集環境をセットアップする、追加のLispライブラリーをロードします。このステップの後には、そのEmacs実行可能形式はbare(裸)ではなくなります。

標準的なLispファイルのロードには若干の時間を要するので、ユーザーが直接temacs実行可能形式を実行することは、通常はありません。そのかわり、Emacsビルドの最終ステップとして、コマンド‘temacs -batch -l loadup dump’が実行されます。特別な引数‘dump’により、temacsはemacsと呼ばれる実行可能形式のプログラムにダンプされます。これには、標準的なLispファイルがすべて事前ロードされています。(引数‘-batch’はtemacsがその端末上でデータの初期化を試みることを防げるので、端末情報のテーブルはダンプされたEmacsでは空になる。)

ダンプされたemacs実行可能形式(純粋なEmacsとも呼ばれる)が、インストールされるEmacsになります。変数preloaded-file-listには、ダンプ済みEmacsに事前ロードされるLispファイルのリストが格納されています。新たなオペレーティングシステムにEmacsをポートする際、そのOSがダンプを実装していなければ、Emacsは起動時に毎回loadup.elをロードしなければなりません。

By default the dumped emacs executable records details such as the build time and host name. Use the --disable-build-details option of configure to suppress these details, so that building and installing Emacs twice from the same sources is more likely to result in identical copies of Emacs.

site-load.elという名前のライブラリーを記述することにより、事前ロードするファイルを追加指定できます。追加するファイルを保持するための純粋なスペースnバイトを追加するように、以下の定義

#define SITELOAD_PURESIZE_EXTRA n

でEmacsをリビルドする必要があるでしょう。src/puresize.hを参考にしてください(十分大きくなるまで、20000▽ずつ増加させる)。しかし、追加ファイルの事前ロードの優位は、マシンの高速化により減少します。現代的なマシンでは、通常はお勧めしません。

loadup.elがsite-load.elを読み込んだ後にSnarf-documentationを呼び出すことにより、それらが格納された場所のファイルetc/DOC内にある、プリミティブと事前ロードされる関数(と変数)のドキュメント文字列を探します(Accessing Documentationを参照)。

site-init.elという名前のライブラリー名に配置することにより、ダンプ直前に実行する他のLisp式を指定できます。このファイルは、ドキュメント文字列を見つけた後に実行されます。

関数または変数の定義を事前ロードしたい場合には、それを行うために、3つの方法があります。それらにより定義ロードして、その後のEmacs実行時にドキュメント文字列をアクセス可能にします:

etc/DOCの生成時にそれらのファイルをスキャンするよう計らい、それらをsite-load.elでロードする。
ファイルをsite-init.elでロードして、Emacsインストール時にLispファイルのインストール先ディレクトリーに、そのファイルをコピーする。
それらの各ファイルで、ローカル変数としてbyte-compile-dynamic-docstringsにnil値を指定して、それらをsite-load.elかsite-init.elでロードする(この手法には、Emacsが毎回そのドキュメント文字列用のスペースを確保するという欠点がある)。

通常の未変更のEmacsでユーザーが期待する何らかの機能を変更するような何かを、site-load.elまたはsite-init.el内に配置することはお勧めしません。あなたのサイトで通常の機能をオーバーライドしなければならないと感じた場合には、default.elでそれを行えば、ユーザーが望む場合にあなたの変更をオーバーライドできます。要約: スタートアップ時のアクション順序を参照してください。site-load.elかsite-init.elのいずれかがload-pathを変更する場合、その変更はダンプ後に失われます。ライブラリー検索を参照してください。load-pathを永続的に変更するには、configureの--enable-locallisppathオプションを指定してください。

事前ロード可能なパッケージでは、その後のEmacsスタートアップまで、特定の評価を遅延させのが必要(または便利)なことがあります。そのようなケースの大半は、カスタマイズ可能な変数の値に関するものです。たとえばtutorial-directoryは、事前ロードされるstartup.el内で定義される変数です。これのデフォルト値は、data-directoryにもとづいてセットされます。この変数はEmacsダンプ時ではなく、スタート時にdata-directoryの値を必要とします。なぜならEmacs実行可能形式はダンプされたものなので、恐らく異なる場所にインストールされます。

Function: custom-initialize-delay symbol value: この関数は、次回のEmacs開始までsymbolの初期化を遅延する。通常は、カスタマイズ可能変数の:initializeプロパティとしてこの関数を指定することにより使用する(引数valueはフォームCustom由来の互換性のためだけに提供されており使用しない)。

custom-initialize-delayが提供するより一般的な機能を要するような稀なケースでは、before-init-hookを使用できます(要約: スタートアップ時のアクション順序を参照)。

Function: dump-emacs to-file from-file

この関数は、Emacsのカレント状態を、実行可能ファイルto-fileにダンプする。これはfrom-file(通常はファイルtemacs)からシンボルを取得する。

すでにダンプ済みのEmacs内でこの関数を使用する場合には、‘-batch’でEmacsを実行しなければならない。

E.2 純粋ストレージ

Emacs Lispはユーザー作成Lispオブジェクトにたいして、通常ストレージ(normal storage)と純粋ストレージ(pure storage)という、2種のストレージをもちます。通常ストレージは、Emacsセッションが維持される間に、新たにデータが作成される場所です。純粋ストレージは、事前ロードされた標準Lispファイル内の、特定のデータのために使用されます。このデータは実際のEmacs使用中に決して変更されるべきではないデータです。

純粋ストレージは、temacsが標準的な事前ローLispライブラリーのロード中だけ割り当てられます。ファイルemacsでは、このメモリースペースは読み取り専用とマークされるので、そのマシン上で実行中のすべてのEmacsジョブで共有できます。純粋ストレージは拡張できません。Emacsのコンパイル時に固定された量が割り当てられ、それが事前ロードされるライブラリーにたいして不足なら、temacsはそれに収まらない部分を動的メモリーに割り当てます。結果イメージは動作するでしょうが、この状況ではメモリーリークとなるので、ガーベージコレクション(ガーベージコレクションを参照)は無効です。そのような通常なら発生しないオーバーフローは、あなたが事前ロードライブラリの追加や、標準的な事前ロードライブラリに追加を試みないかぎり発生しません。Emacsはオーバーロードの開始時に、オーバーロードに関する警告を表示するでしょう。これが発生したら、ファイルsrc/puresize.h内のコンパイルパラメーターをSYSTEM_PURESIZE_EXTRAを増やして、Emacsをリビルドする必要があります。

Function: purecopy object

この関数は純粋ストレージにobjectのコピーを作成して、それをリターンする。これは同じ文字で新たに文字列を作成することにより文字列をコピーするが、純粋ストレージではテキストプロパティはない。これはベクターとコンスセルのコンテンツを、再帰的にコピーする。シンボルのような他のオブジェクトのコピーは作成しないが、それらを未変更でリターンする。マーカーのコピーを試みると、エラーをシグナルする。

この関数は、Emacsのビルド中とダンプ中を除き、何もしない。通常は事前ロードされるLispファイル内でのみ呼び出される。

Variable: pure-bytes-used: この変数の値は、これまでに割り当てられた純粋ストレージのバイト数である。ダンプされたEmacsでは、通常は利用可能な純粋ストレージの総量とほとんど同じであり、もしそうでないならわたしたちは事前割り当てをもっと少なくするだろう。

Variable: purify-flag

この変数は、defunが純粋ストレージにその関数定義のコピーを作成するべきか否かを判断する。これが非nilなら、その関数の定義は純粋ストレージにコピーされる。

このフラグは、Emacsのビルド用の基本的な関数の初回ロード中はtとなる。実行可能形式としてEmacsをダンプすることにより、ダンプ前後の実際の値とは無関係に、常にこの変数にnilが書き込まれる。

実行中のEmacsで、このフラグを変更しないこと。

E.3 ガーベージコレクション

プログラムがリストを作成するときや、(ライブライのロード等により)ユーザーが新しい関数を定義する際、そのデータは通常ストレージに配置されます。通常ストレージが少なくなると、Emacsはもっとメモリーを割り当てるようオペレーティングシステムに要求します。シンボル、コンスセル、小さいベクター、マーカー等のような別のタイプのLispオブジェクトは、メモリー内の個別のブロックに隔離されます(大きいベクター、長い文字列、バッファー、および他の特定の編集タイプは非常に巨大であり、1つのオブジェクトにたいして個別のブロックが割り当てられ、小さな文字列は8kバイトのブロック、小さいベクターは4kバイトのブロックにパックされる)。

Beyond the basic vector, a lot of objects like window, buffer, and frame are managed as if they were vectors. The corresponding C data structures include the union vectorlike_header field whose size member contains the subtype enumerated by enum pvec_type and an information about how many Lisp_Object fields this structure contains and what the size of the rest data is. This information is needed to calculate the memory footprint of an object, and used by the vector allocation code while iterating over the vector blocks.

しばらくの間いくつかのストレージを使用して、(たとえば)バッファーのkillやあるオブジェクトを指す最後のポインターの削除によりそれを開放するのは、非常に一般的なことです。この放棄されたストレージを再利用するために、Emacsはガーベージコレクター(garbage collector)を提供します。ガーベージコレクターは、いまだLispプログラムからアクセス可能なすべてのLispオブジェクトを検索、マークすることにより動作します。これを開始するには、すべてのシンボル、それらの値と関連付けられている関数定義、現在スタック上にあるすべてのデータをアクセス可能と仮定します。別のアクセス可能オブジェクトを介して間接的に到達できるスベテのオブジェクトも、アクセス可能とみなされます。

When marking is finished, all objects still unmarked are garbage. No matter what the Lisp program or the user does, it is impossible to refer to them, since there is no longer a way to reach them. Their space might as well be reused, since no one will miss them. The second (sweep) phase of the garbage collector arranges to reuse them.

スイープフェーズは将来の割り当て用に、シンボルやマーカーと同様に、未使用のコンスセルをフリーリスト(free list)上に配置します。これは、アクセス可能な文字列は少数の8kブロックを占有するように圧縮して、その後に他の8kブロックを開放します。ベクターブロックから到達不可能はベクターは、可能なかぎり最大のフリーエリアを作成するために統合し、フリーエリアが完全な4kブロックに跨がるようなら、そのブロックは開放されます。それ以外なら、そのフリーエリアはフリーリスト配列に記録されます。これは、各エントリーが同サイズのエリアのフリーリストに対応します。巨大なベクター、バッファー、その他の巨大なオブジェクトは、個別に割り当てと開放が行われます。

Common Lispに関する注意: 他のLispと異なり、GNU Emacs Lispはフリーリストが空のときにガーベージコレクターを呼び出さない。かわりに、単にオペレーティングシステムに更なるストレージの割り当てを要求して、gc-cons-thresholdバイトを使い切るまで処理を継続する。

これは特定のLispプログラムの範囲の実行直前に、明示的にガーベージコレクターを呼び出せば、その範囲の実行中はガーベージコレクターが実行されないだろうと確信できることを意味する(そのプログラム範囲が2回目のガーベージコレクションを強制するほど、多くのスペースを使用しないという前提)。

Command: garbage-collect

このコマンドはガーベージコレクションを実行して、使用中のスペース量の情報をリターンする(前回のガーベージコレクション以降、gc-cons-thresholdバイトより多いLispデータを使用した場合には、自然にガーベージコレクションが発生することもあり得る)。

garbage-collectは使用中のスペース量の情報をリストでリターンする。これの各エントリーは‘(name size used)’という形式をもつ。このエントリーでnameはそのエントリーが対応するオブジェクトの種類を記述するシンボル、sizeはそれが使用するバイト数、usedはヒープ内で生きていることが解ったオブケウトの数、オプションのfreeは、生きていないがEmacsが将来の割り当て用に保持しているオブジェクトの数である。全体的な結果は以下のようになる:

((conses cons-size used-conses free-conses)
 (symbols symbol-size used-symbols free-symbols)
 (miscs misc-size used-miscs free-miscs)
 (strings string-size used-strings free-strings)
 (string-bytes byte-size used-bytes)
 (vectors vector-size used-vectors)
 (vector-slots slot-size used-slots free-slots)
 (floats float-size used-floats free-floats)
 (intervals interval-size used-intervals free-intervals)
 (buffers buffer-size used-buffers)
 (heap unit-size total-size free-size))

以下に例を示す:

(garbage-collect)
      ⇒ ((conses 16 49126 8058) (symbols 48 14607 0)
                 (miscs 40 34 56) (strings 32 2942 2607)
                 (string-bytes 1 78607) (vectors 16 7247)
                 (vector-slots 8 341609 29474) (floats 8 71 102)
                 (intervals 56 27 26) (buffers 944 8)
                 (heap 1024 11715 2678))

以下は、各要素を説明するためのテーブルである。最後のheapエントリーはオプションであり、背景のmalloc実装がmallinfo関数を提供する場合のみ与えられることに注意。

cons-size: コンスセルの内部的サイズ(sizeof (struct Lisp_Cons))。
used-conses: 使用中のコンスセルの数。
free-conses: オペレーティングシステムから取得したスペースにあるが、カレントで未使用のコンスセルの数。
symbol-size: シンボルの内部的サイズ(sizeof (struct Lisp_Symbol))。
used-symbols: 使用中のシンボルの数。
free-symbols: オペレーティングシステムから取得したスペースにあるが、カレントで未使用のシンボルの数。
misc-size: 雑多なエンティティーの内部的なサイズ。sizeof (union Lisp_Misc)はenum Lisp_Misc_Typeに列挙された最大タイプのサイズ。
used-miscs: 使用中の雑多なエンティティーの数。これらのエンティティーにはマーカー、オーバーレイに加えて、ユーザーにとって不可視な特定オブジェクトが含まれる。
free-miscs: オペレーティングシステムから取得したスペースにあるが、カレントで未使用の雑多なオブジェクトの数。
string-size: 文字列ヘッダーの内部的サイズ(sizeof (struct Lisp_String))。
used-strings: 使用中の文字列ヘッダーの数。
free-strings: オペレーティングシステムから取得したスペースにあるが、カレントで未使用の文字列ヘッダーの数。
byte-size: これは利便性のために使用され、sizeof (char)と同じ。
used-bytes: すべての文字列データの総バイト数。
vector-size: ベクターヘッダーの内部的サイズ(sizeof (struct Lisp_Vector))。
used-vectors: ベクターブロックから割り当てられたベクターブロック数。
slot-size: ベクタースロットの内部的なサイズで、常にsizeof (Lisp_Object)と等しい。
used-slots: 使用されているすべてのベクターのスロット数。
free-slots: すべてのベクターブロックのフリースロットの数。
float-size: 浮動小数点数オブジェクトの内部的なサイズ(sizeof (struct Lisp_Float))。(ネイティブプラットフォームのfloatやdoubleと混同しないこと。)
used-floats: 使用中の浮動小数点数の数。
free-floats: オペレーティングシステムから取得したスペースにあるが、カレントで未使用の浮動小数点数の数。
interval-size: インターバルオブジェクト(interval object)の内部的なサイズ(sizeof (struct interval))。
used-intervals: 使用中のインターバルの数。
free-intervals: オペレーティングシステムから取得したスペースにあるが、カレントで未使用のインターバルの数。
buffer-size: バッファーの内部的なサイズ(sizeof (struct buffer))。(buffer-size関数がリターンする値と混同しないこと。)
used-buffers: 使用中のバッファーオブジェクトの数。これにはユーザーからは不可視のkillされたバッファー、つまりリストall_buffers内のバッファーすべてが含まれる。
unit-size: ヒープスペースを計る単位で、常に1024バイトと等しい。
total-size: unit-size単位での総ヒープサイズ。
free-size: unit-size単位での、カレントで未使用のヒープスペース。

純粋スペース(純粋ストレージを参照)内にオーバーフローがあれば、実際にガーベージコレクションを行うことは不可能なので、garbage-collectはnilをリターンする。

User Option: garbage-collection-messages: この変数が非nilなら、Emacsはガーベージコレクションの最初と最後にメッセージを表示する。デフォルト値はnil。

Variable: post-gc-hook: これはガーベージコレクションの終わりに実行される、ノーマルフックである。ガーベージコレクションは、このフックの関数の実行中は抑制されるので、慎重に記述されたい。

User Option: gc-cons-threshold

この変数の値は、別のガーベージコレクションをトリガーするために、ガーベージコレクション後にLispオブジェクト用に割り当てなければならない、ストレージのバイト数である。特定ノオブジェクトタイプに関する情報を取得するために、garbage-collectがリターンした結果を使用できる。バッファーのコンテンツに割り当てられたスペースは、勘定に入らない。後続のガーベージコレクションは、このthreshold(閾値)が消費されても即座には実行されず、次回にLispインタープリターが呼び出されたときのみ実行されることに注意。

thresholdの初期値はGC_DEFAULT_THRESHOLDで、これはalloc.c内で定義されている。これはword_size単位で定義されているので、デフォルトの32ビット設定では400,000800,000、64ビット設定ではになる。大きい値を指定すると、ガーベージコレクションの頻度が下る。これはガーベージコレクションにより費やされる時間を減少させるが、メモリーの総使用量は増大する。大量のLispデータを作成するプログラムの実行時には、これを行いたいと思うかもしれない。

GC_DEFAULT_THRESHOLDの1/10まで下げた小さな値を指定することにより、より頻繁にガーベージコレクションを発生させることができる。この最小値より小さい値は、後続のガーベージコレクションで、garbage-collectがthresholdを最小値に戻すときまでしか効果をもたないだろう。

User Option: gc-cons-percentage

この変数の値は、ガーベージコレクション発生するまでのコンス(訳注: これはgc-cons-thresholdやgc-cons-percentageの‘-cons-’のことで、これらの変数が定義されているalloc.c内では、Lisp方言での‘cons’をより一般化したメモリー割り当てプロセスのことを指すようです)の量を、カレントヒープサイズにたいする割り合いで指定する。この条件とgc-cons-thresholdを並行して適用し、条件が両方満足されたときだけ、ガーベージコレクションが発生する。

ヒープサイズ増加にともない、ガーベージコレクションの処理時間は増大する。したがって、ガーベージコレクションの頻度割合を減らすのが望ましいことがある。

garbage-collectがリターンする値は、データ型に分類されたLispデータノめもりー使用量を記述します。それと対照的に関数memory-limitは、Emacsがカレントで使用中の総メモリー量の情報を提供します。

Function: memory-limit

この関数は、Emacsが割り当てたメモリーの最後のバイトアドレスを1024で除した値をリターンする。その値を1024で除しているのは、Lisp整数に収まるようにするためである。

あなたのアクションがメモリー使用に与える影響について、大まかなアイデアを得るために、これを使用することができる。

Variable: memory-full: この変数は、Lispオブジェクト用のメモリーが不足に近い状態ならt、それ以外ならnilとなる。

Function: memory-use-counts: これはそのEmacsセッションで作成されたオブジェクト数をカウントしたリストである。これらのカウンターはそれぞれ、特定の種類のオブジェクトを数える。詳細はドキュメント文字列を参照のこと。

Function: memory-info: This functions returns an amount of total system memory and how much of it is free. On an unsupported system, the value may be nil.

Variable: gcs-done: この変数は、そのEmacsセッションでそれまでに行われたガーベージコレクションの合計回数である。

Variable: gc-elapsed: この変数は、そのEmacsセッションでガーベージコレクションの間に費やされた経過時間を、浮動小数点数で表した総秒数である。

E.4 Stack-allocated Objects

The garbage collector described above is used to manage data visible from Lisp programs, as well as most of the data internally used by the Lisp interpreter. Sometimes it may be useful to allocate temporary internal objects using the C stack of the interpreter. This can help performance, as stack allocation is typically faster than using heap memory to allocate and the garbage collector to free. The downside is that using such objects after they are freed results in undefined behavior, so uses should be well thought out and carefully debugged by using the GC_CHECK_MARKED_OBJECTS feature (see src/alloc.c). In particular, stack-allocated objects should never be made visible to user Lisp code.

Currently, cons cells and strings can be allocated this way. This is implemented by C macros like AUTO_CONS and AUTO_STRING that define a named Lisp_Object with block lifetime. These objects are not freed by the garbage collector; instead, they have automatic storage duration, i.e., they are allocated like local variables and are automatically freed at the end of execution of the C block that defined the object.

For performance reasons, stack-allocated strings are limited to ASCII characters, and many of these strings are immutable, i.e., calling ASET on them produces undefined behavior.

E.5 メモリー使用量

以下の関数と変数は、Emacsが行なったメモリー割り当ての総量に関する情報を、データ型ごとに分類して提供します。これらの関数や変数と、garbage-collectがリターンする値との違いに注意してください。garbage-collectはカレントで存在するオブジェクトを数えますが、以下の関数および変数はすでに開放されたオブジェクトを含めて、すべての割り当ての数またはサイズを数えます。

Variable: cons-cells-consed: そのEmacsセッションで、それまでに割り当てられたコンスセルの総数。

Variable: floats-consed: そのEmacsセッションで、それまでに割り当てられた浮動小数点数の総数。

Variable: vector-cells-consed: そのEmacsセッションで、それまでに割り当てられたベクターセル

Variable: symbols-consed: そのEmacsセッションで、それまでに割り当てられたシンボルの総数。

Variable: string-chars-consed: そのEmacsセッションで、それまでに割り当てられた文字列の文字の総数。

Variable: misc-objects-consed: そのEmacsセッションで、それまでに割り当てられた雑多なオブジェクトの総数。これにはマーカー、オーバーレイに加えて、ユーザーには不可視な特定のオブジェクトが含まれる。

Variable: intervals-consed: そのEmacsセッションで、それまでに割り当てられたインターバルの総数。

Variable: strings-consed: そのEmacsセッションで、それまでに割り当てられた文字列の総数。

E.6 C方言

The C part of Emacs is portable to C99 or later: C11-specific features such as ‘<stdalign.h>’ and ‘_Noreturn’ are not used without a check, typically at configuration time, and the Emacs build procedure provides a substitute implementation if necessary. Some C11 features, such as anonymous structures and unions, are too difficult to emulate, so they are avoided entirely.

At some point in the future the base C dialect will no doubt change to C11.

E.7 Emacsプリミティブの記述

Lispプリミティブとは、Cで実装されたLisp関数です。Lispから呼び出せるように、C関数インターフェースの詳細は、Cのマクロで処理されます。新たなCコードの記述のしかたを真に理解するには、ソースを読むのが唯一の方法ですが、ここではいくつかの事について説明します。

スペシャルフォームの例として、以下はeval.cのorです(通常の関数は、同様の一般的な外観をもつ)。

DEFUN ("or", For, Sor, 0, UNEVALLED, 0,
  doc: /* Eval args until one of them yields non-nil, then return
that value.
The remaining args are not evalled at all.
If all args return nil, return nil.

usage: (or CONDITIONS...)  */)
  (Lisp_Object args)
{
  Lisp_Object val = Qnil;

  while (CONSP (args))
    {
      val = eval_sub (XCAR (args));
      if (!NILP (val))
        break;
      args = XCDR (args);
      maybe_quit ();
    }

  return val;
}

ではDEFUNマクロの引数について、詳細に説明しましょう。以下は、それらのテンプレートです:

DEFUN (lname, fname, sname, min, max, interactive, doc)

lname

これは、関数名として定義する、Lispシンボル名である。上記例ではor。

fname

これは、その関数のC関数名である。これはCコードでその関数を呼び出すために使用される名前である。名前は慣習として‘F’の後にLisp名をつけ、Lisp名のすべてのダッシュ(‘-’)は、アンダースコアに変更する。つまりCコードから呼び出す場合は、Forを呼び出す。

sname

これは、Lispでその関数を表すsubrオブジェクト用に、データ保持のための構造体に使用されるC変数名である。この構造体は、そのシンボルを作成してそれの定義にsubrオブジェクトを格納する初期化ルーチンにおいて、Lispシンボル名を伝達する。慣習により、これは常にfnameの‘F’を‘S’に置き換えた名前になる

min

これは、その関数が要求する、引数の最小個数である。関数orは、最小で0個の関数を受け入れる。

max

これは、その関数が受け入れる引数の最大個数が定数なら、引数の最大個数である。またはUNEVALLEDならそれは未評価の引数を受け取るスペシャルフォームを示し、MANYなら評価される引数の個数に制限がないことを意味する(&restと等価)。UNEVALLEDとMANYは、いずれもマクロである。maxが数字ならそれはminより大きく、8より小さいこと。

interactive

これはLisp関数でinteractiveの引数として使用されるような、インタラクティブ仕様である(文字列)。orの場合は0(nullポインター)で、それはorがインタラクティブに呼び出せないことを示す。値""は、インタラクティブに呼び出し時、関数が引き受けるべきではないことを示す。値が‘"(’で始まる場合、その文字列はLispフォームとして評価される。たとえば:

DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, 0
       "(list (read-char-by-name \"Insert character: \")\
              (prefix-numeric-value current-prefix-arg)\
              t))",
  doc: /* … */)

doc

これはドキュメント文字列である。複数行を含むために特別なことを要しないので、これにはCの文字列構文ではなく、Cコメント構文を使用する。‘doc:’の後のコメントは、ドキュメント文字列として認識する。コメントの開始と終了の区切り文字‘/*’と‘*/’は、ドキュメント文字列の一部にはならない。

ドキュメント文字列の最後の行がキーワード‘usage:’で始まる場合、その行の残りの部分は引数リストをドキュメント化するためのものとして扱われる。この方法により、Cコード内で使用される引数名とは異なる引数名を、ドキュメント文字列内で使用することができる。その関数の引数の個数に制限がない場合、‘usage:’は必須。

Lispコードでのドキュメント文字列にたいする通常ルールのすべて(ドキュメント文字列のヒントを参照)は、Cコードのドキュメント文字列にも適用される。

The documentation string can be followed by a list of C function attributes for the C function that implements the primitive, like this:

DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0
  doc: /* … */
  attributes: attr1 attr2 …)

You can specify more than a single attribute, one after the other. Currently, only the following attributes are recognized:

noreturn: Declares the C function as one that never returns. This corresponds to the C11 keyword _Noreturn and to __attribute__ ((__noreturn__)) attribute of GCC (see Function Attributes in Using the GNU Compiler Collection).
const: Declares that the function does not examine any values except its arguments, and has no effects except the return value. This corresponds to __attribute__ ((__const__)) attribute of GCC.
noinline: This corresponds to __attribute__ ((__noinline__)) attribute of GCC, which prevents the function from being considered for inlining. This might be needed, e.g., to countermand effects of link-time optimizations on stack-based variables.

DEFUNマクロ呼び出しの後には、そのC関数にたいする引数リストを、その引数のタイプを含めて記述しなければなりません。そのプリミティブがLispで固定された最大個数をもつ引数を受け入れるなら、Lisp引数それぞれにたいして1つのC引数をもち、各引数のタイプはLisp_Objectでなければなりません(ファイルlisp.hでは、タイプLisp_Objectの値を作成する種々のマクロと関数が宣言されている)。そのプリミティブのLispの最大引数個数に上限がない場合、それは正確に2つのC引数をもたなければなりません。1つ目はLisp引数の個数で、2つ目はそれらの値を含むブロックのアドレスです。これらはそれぞれint、Lisp_Object *のタイプをもちます。Lisp_Objectは任意のデータ型と任意のLispオブジェクトを保持できるので、実行時のみ実際のデータ型を判断できます。特定のタイプの引数だけを受け入れるプリミティブを記述したい場合は、適切な述語を使用してタイプを明確にチェックしなければなりません(型のための述語を参照)。

Within the function For itself, the local variable args refers to objects controlled by Emacs’s stack-marking garbage collector. Although the garbage collector does not reclaim objects reachable from C Lisp_Object stack variables, it may move non-object components of an object, such as string contents; so functions that access non-object components must take care to refetch their addresses after performing Lisp evaluation. Lisp evaluation can occur via calls to eval_sub or Feval, either directly or indirectly.

Note the call to maybe_quit inside the loop: this function checks whether the user pressed C-g, and if so, aborts the processing. You should do that in any loop that can potentially require a large number of iterations; in this case, the list of arguments could be very long. This increases Emacs responsiveness and improves user experience.

一度Emacsがダンプされた後に、その変数に何か書き込まれているときには、その静的変数またはグローバル変数に、Cの初期化を使用してはなりません。初期化されたこれらの変数は、Emacsのダンプの結果として、(特定のオペレーティングシステムでは)読み取り専用となるメモリーエリアに割り当てられます。純粋ストレージを参照してください。

C関数の定義だけでは、Lispプリミティブを利用可能にするのに十分ではありません。そのプリミティブにたいしてLispシンボルを作成して、その関数セルに適切なsubrオブジェクトを格納しなければなりません。このコードは以下のようになるでしょう:

defsubr (&sname);

ここでsnameは、DEFUNの3つ目の引数として使用する名前です。

すでにLispプリミティブが定義されたファイルにプリミティブを追加する場合には、(そのファイル終端付近にある)syms_of_somethingという名前の関数を探して、そこにdefsubrの呼び出しを追加してください。そのファイルにこの関数がない、または新たなファイルを作成する場合には、それにsyms_of_filename(例: syms_of_myfile)を追加します。それからemacs.cで、それらの関数すべてが呼び出されるが呼び出される箇所を探して、そこにsyms_of_filenameの呼び出しを追加してください。

関数syms_of_filenameは、Lisp変数として可視となるすべてのC変数を定義する場所でもあります。DEFVAR_LISPはタイプLisp_ObjectのC変数を、Lispから可視にします。DEFVAR_INTはタイプintのC変数を、常に整数となる値をもつようにして、Lispから可視にします。DEFVAR_BOOLはタイプintのC変数を、常にtかnilのいずれかとなる値をもつようにして、Lispから可視にします。DEFVAR_BOOLで定義された変数は、バイトコンパイラーに使用されるリストbyte-boolean-varsに、自動的に追加されることに注意してください。

If you want to make a Lisp variable that is defined in C behave like one declared with defcustom, add an appropriate entry to cus-start.el.

タイプLisp_ObjectのファイルをスコープとするC変数を定義する場合には、以下のようにsyms_of_filename内でstaticproを呼び出して、ガーベージコレクションからそれを保護しなければなりません:

staticpro (&variable);

以下は、より複雑な引数をもつ別の関数例です。これはwindow.cからのコードで、Lispオブジェクトを操作するためのマクロと関数の使用を示すものです。

DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
  Scoordinates_in_window_p, 2, 2, 0,
  doc: /* Return non-nil if COORDINATES are in WINDOW.
  ...

  or `right-margin' is returned.  */)
  (register Lisp_Object coordinates, Lisp_Object window)
{
  struct window *w;
  struct frame *f;
  int x, y;
  Lisp_Object lx, ly;

  CHECK_LIVE_WINDOW (window);
  w = XWINDOW (window);
  f = XFRAME (w->frame);
  CHECK_CONS (coordinates);
  lx = Fcar (coordinates);
  ly = Fcdr (coordinates);
  CHECK_NUMBER_OR_FLOAT (lx);
  CHECK_NUMBER_OR_FLOAT (ly);
  x = FRAME_PIXEL_X_FROM_CANON_X (f, lx) + FRAME_INTERNAL_BORDER_WIDTH(f);
  y = FRAME_PIXEL_Y_FROM_CANON_Y (f, ly) + FRAME_INTERNAL_BORDER_WIDTH(f);

  switch (coordinates_in_window (w, x, y))
    {
    case ON_NOTHING:            /* NOT in window at all.  */
      return Qnil;

...

    case ON_MODE_LINE:          /* In mode line of window.  */
      return Qmode_line;

...

    case ON_SCROLL_BAR:         /* On scroll-bar of window.  */
      /* Historically we are supposed to return nil in this case.  */
      return Qnil;

    default:
      abort ();
    }
}

Note that C code cannot call functions by name unless they are defined in C. The way to call a function written in Lisp is to use Ffuncall, which embodies the Lisp function funcall. Since the Lisp function funcall accepts an unlimited number of arguments, in C it takes two: the number of Lisp-level arguments, and a one-dimensional array containing their values. The first Lisp-level argument is the Lisp function to call, and the rest are the arguments to pass to it.

C関数call0、call1、call2、...は個数が固定された引数でLisp関数を手軽に呼び出す、便利な方法を提供します。これらはFfuncallを呼び出すことにより機能します。

eval.cは例を探すには、よいファイルです。lisp.hには、重要なマクロと関数の定義がいくつか含まれています。

副作用をもたない関数を定義する場合には、コンパイラーのオプティマイザーに知らせるためにside-effect-free-fnsとside-effect-and-error-free-fnsをバインドする、byte-opt.el内のコードを更新してください。

E.8 オブジェクトの内部

Emacs Lispは豊富なデータタイプのセットを提供します。コンスセル、整数、文字列のようにこれらのいくつかは、ほとんどすべてのLisp方言で一般的です。マーカやバッファーのようなそれ以外のものは、Lisp内でエディターコマンドを記述するための基本的サポートを提供するために、極めて特別で必要なものです。そのような種々のオブジェクトタイプを実装して、インタープリターのサブシステムとの間でオブジェクトを渡す効果的な方法を提供するに、Cデータ構造体セットとそれらすべてにたいするポインターを表す、タグ付きポインター(tagged pointer)と呼ばれる、特別なタイプが存在します。

Cでは、タグ付きポインターは、タイプLisp_Objectのオブジェクトです。そのようなタイプの初期化された変数は、基本的なデータタイプである整数、シンボル、文字列、コンスセル、浮動小数点数、ベクター類似オブジェクトや、その他の雑多なオブジェクトのいずれかを、常に値として保持します。これらのデータタイプのそれぞれは、対応するタグ値をもちます。すべてのタグはenum Lisp_Typeにより列挙され、Lisp_Objectの3ビットのビットフィールソに配置されます。残りのビットは、それ自身の値です。整数は即値(値ビットで直接表される)、他のすべてのオブジェクトは、ヒープに割り当てられた対応するオブジェクトへのCポインターで表されます。Lisp_Objectのサイズはプラットフォームと設定に依存します。これは通常は背景プラットフォームのポインターと等しい(32ビットマシンなら32ビット、64ビットマシンなら64ビット)ですが、Lisp_Objectが64ビットでも、すべてのポインターが32ビットのような特別な構成もあります。後者はLisp_Objectにたいして、64ビットのlong longタイプを使用することにより、32ビットシステム上のLisp整数にたいする、値範囲の制限を乗り越えるためにデザインされたトリックです。

以下のCデータ構造体は、整数ではない基本的なデータタイプを表すために、lisp.hで定義されています:

struct Lisp_Cons: コンスセル。リストを構築するために使用されるオブジェクトである。
struct Lisp_String: 文字列。文字シーケンスを表す基本的オブジェクトである。
struct Lisp_Vector: 配列。インデックスによりアクセスできる、固定サイズのLispオブジェクトのセットである。
struct Lisp_Symbol: シンボル。一般的に識別子として使用される一意な名前のエンティティである。
struct Lisp_Float: Floating-point value.
union Lisp_Misc: 上記のいずれにも適合しない、雑多な種類のオブジェクト。

これらのタイプは、内部的タイプシステムの一級クラスの市民です。タグスペースは限られているので、他のすべてのタイプはLisp_VectorlikeかLisp_Miscのサブクラスです。サブタイプのベクターはenum pvec_typeにより列挙されておりウィンドウ、バッファー、フレーム、プロセスのようなほとんどすべての複雑なオブジェクトは、このカテゴリーに分類されます。マーカーとオーバーレイを含む残りのスペシャルタイプは、enum Lisp_Misc_Typeにより列挙されており、Lisp_Miscのサブタイプセットを形成します。

Lisp_Vectorlikeのいくつかのサブタイプを説明します。バッファーオブジェクトは、表示および編集を行うテキストを表します。ウィンドウはバッファーを表示したり、同一フレーム上で再帰的に他のウィンドウを配置するためのコンテナーに使用される、表示構造の一部です(Emacs Lispのウィンドウオブジェクトと、Xのようなユーザーインターフェースシステムに管理されるエンティティとしてのウィンドウを混同しないこと。Emacsの用語では後者はフレームと呼ばれる)。最後に、プロセスオブジェクトは、サブプロセスの管理に使用されます。

E.8.1 バッファーの内部

2つの構造体(buffer.hを参照)は、Cでバッファーを表すために使用されます。buffer_text構造体には、バッファーのテキストを記述するフィールドが含まれます。buffer構造体は他のフィールドを保持します。インダイレクトバッファーの場合には、2つ以上のbuffer構造体が、同じbuffer_text構造体を参照します。

以下にstruct buffer_text内のフィールドをいくつか示します:

beg: バッファーコンテンツのアドレス。
gpt
gpt_byte: バッファーのギャップの文字位置とバイト位置。バッファーのギャップを参照のこと。
z
z_byte: バッファーテキストの終端の文字位置とバイト位置。
gap_size: バッファーのギャップのサイズ。バッファーのギャップを参照のこと。
modiff
save_modiff
chars_modiff
overlay_modiff: これらのフィールドは、そのバッファーで行われた、バッファー変更イベントの数をカウントする。modiffはバッファー変更イベントのたびに増分され、それ以外では決して変化しない。save_modiffには、そのバッファーが最後にvisitまたは保存されたときの、modiffの値が含まれる。chars_modiffは、そのバッファー内の文字にたいする変更だけをカウントし、その他すべての種類の変更を無視する。overlay_modiffは、オーバーレイにたいする変更だけをカウントする。
beg_unchanged
end_unchanged: 最後の再表示完了以降に、未変更だと解っているテキストの、開始と終了の箇所での文字数。
unchanged_modified
overlay_unchanged_modified: それぞれ、最後に再表示が完了した後のmodiffとoverlay_modiffの値。これらのカレント値がmodiffやoverlay_modiffとマッチしたら、それはbeg_unchangedとend_unchangedに有用な情報が含まれないことを意味する。
markers: このバッファーを参照するマーカー。これは実際には単一のマーカーであり、自身のマーカー“チェーン”内の一連の要素が、そのバッファー内のテキストを参照する他のマーカーになる。
intervals: そのバッファーのテキストプロパティを記録する、インターバルツリー。

struct bufferのいくつかのフィールドを以下に示します:

header: A header of type union vectorlike_header is common to all vectorlike objects.
own_text: 構造体struct buffer_textは、通常はバッファーのコンテンツを保持する。インダイレクトバッファーでは、このフィールドは使用されない。
text: そのバッファーのbuffer_text構造体へのポインター。通常のバッファーでは、上述のown_textフィールドである。インダイレクトバッファーでは、そのベースバッファーのown_textフィールドになる。
next: killされたバッファーを含むすべてのバッファーのチェーン内において、次のバッファーへのポインター。このチェーンは、killされたバッファーを正しく回収するために、割り当てとガーベージコレクションのためだけに使用される。
pt
pt_byte: バッファー内のポイントの文字位置とバイト位置。
begv
begv_byte: そのバッファー内のアクセス可能範囲の、先頭位置の文字位置とバイト位置。
zv
zv_byte: そのバッファー内のアクセス可能範囲の、終端位置の文字位置とバイト位置。
base_buffer: インダイレクトバッファーでは、これはベースバッファーのポイントである。通常のバッファーではnull。
local_flags: このフィールドは、そのバッファー内でローカルな変数にたいして、それを示すフラグを含む。そのような変数はCコードではDEFVAR_PER_BUFFERを使用して宣言され、それらのバッファーローカルなバインディングは、このバッファー構造体自身内のフィールドに格納される(これらのフィールドのいくつかは、このテーブル内で説明されておる)。
modtime: visitされているファイルの変更時刻。これは、そのファイルの書き込みおよび読み込み時にセットされる。そのバッファーをファイルに書き込む前に、そのファイルがディスク上で変更されていないことを確認するために、このフィールドとそのファイルの変更時刻を比較する。バッファーの変更を参照のこと。
auto_save_modified: そのバッファーが最後に自動保存さらたときの時刻。
last_window_start: そのバッファー最後にウィンドウに表示されたときの、のwindow-start位置。
clip_changed: このフラグは、そのバッファーでのナローイングが変更されているかを示す。ナローイングを参照のこと。
prevent_redisplay_optimizations_p: このフラグは、そのバッファーの表示において、再表示最適化が使用されるべきではないことを示す。
overlay_center: このフィールドは、カレントオーバーレイの中心位置を保持する。オーバーレイの管理を参照のこと。
overlays_before
overlays_after: これらのフィールドは、カレントオーバーレイ中心、またはその前で終わるオーバーレイのリスト、およびカレントオーバーレイの後で終わるオーバーレイのリストである。オーバーレイの管理を参照のこと。overlays_beforeは終端位置の記述順に格納され、overlays_afterは先頭位置増加順で格納される。
name: そのバッファーを命名するLisp文字列。これは一意であることが保証されている。バッファーの名前を参照のこと。
save_length: そのバッファーがvisitしているファイルを、最後に読み込みまたは保存したときの長さ。インダイレクトバッファーは決して保存されることはないので、保存に関して、このフィールドとその他のフィールドは、buffer_text構造体で維持されない
directory: 相対ファイル名を展開するディレクトリー。これはバッファーローカル変数default-directoryの値である(ファイル名を展開する関数を参照)。
filename: そのバッファーがvisitしているファイルの名前。これは、バッファーローカル変数buffer-file-nameの値である(バッファーのファイル名を参照)。
undo_list
backed_up
auto_save_file_name
auto_save_file_format
read_only
file_format
file_truename
invisibility_spec
display_count
display_time: これらのフィールドは、自動的にバッファーローカル(バッファーローカル変数を参照)になるLisp変数の値を格納する。これらに対応する変数は、名前に追加のプレフィクスbuffer-がつき、アンダースコアがダッシュで置換される。たとえばundo_listは、buffer-undo-listの値を格納する。
mark: そのバッファーにたいするマーク。マークはマーカーなので、リストmarkers内にも含まれる。マークを参照のこと。
local_var_alist: この連想リストは、そのバッファーのバッファーローカル変数のバインディングを記述する。これにはバッファーオブジェクト内に特別なスロットをもつ、ビルトインのバッファーローカルなバインディングは含まれない(このテーブルでは、それらのスロットは省略している)。バッファーローカル変数を参照のこと。
major_mode: そのバッファーのメジャーモードを命名するシンボル(例: lisp-mode)。
mode_name: そのメジャーモードの愛称(例: "Lisp")。
keymap
abbrev_table
syntax_table
category_table
display_table: これらのフィールドは、そのバッファーのローカルキーマップ(キーマップを参照)、abbrevテーブル(abbrevテーブルを参照)、構文テーブル(構文テーブルを参照)、カテゴリーテーブル(カテゴリーを参照)、ディスプレーテーブル(ディスプレーテーブルを参照)を格納する。
downcase_table
upcase_table
case_canon_table: これらのフィールドはテキストを小文字、大文字、およびcase-fold検索でのテキストの正規化の変換テーブルを格納する。caseテーブルを参照のこと。
minor_modes: そのバッファーのマイナーモードのalist。
pt_marker
begv_marker
zv_marker: これらのフィールドはインダイレクトバッファー、またはインダイレクトバッファーのベースバッファーであるようなバッファーでのみ使用される。これらはそれぞれ、そのバッファーがカレントでないときに、そのバッファーにたいするpt、begv、zvを記録するマーカーを保持する。
mode_line_format
header_line_format
case_fold_search
tab_width
fill_column
left_margin
auto_fill_function
truncate_lines
word_wrap
ctl_arrow
bidi_display_reordering
bidi_paragraph_direction
selective_display
selective_display_ellipses
overwrite_mode
abbrev_mode
mark_active
enable_multibyte_characters
buffer_file_coding_system
cache_long_line_scans
point_before_scroll
left_fringe_width
right_fringe_width
fringes_outside_margins
scroll_bar_width
indicate_empty_lines
indicate_buffer_boundaries
fringe_indicator_alist
fringe_cursor_alist
scroll_up_aggressively
scroll_down_aggressively
cursor_type
cursor_in_non_selected_windows: これらのフィールドは、自動的にバッファーローカル(バッファーローカル変数を参照)になるLisp変数の値を格納する。これらに対応する変数は、名前のアンダースコアがダッシュで置換される。たとえばmode_line_formatは、mode-line-formatの値を格納する。
last_selected_window: これは、最後に選択されていたときにそのバッファーを表示していたウィンドウ、またはそのウィンドウがすでにそのバッファーを表示していなければnilである。

E.8.2 ウィンドウの内部

ウィンドウのフィールドには、以下が含まれます(完全なリストはwindow.hのstruct windowを参照されたい):

frame

そのウィンドウがあるフレーム。

mini_p

そのウィンドウがミニバッファーウィンドウなら非nil。

parent

Emacsは内部的に、ウィンドウをツリーにアレンジする。ウィンドウの兄弟グループは、そのエリアがすべての兄弟を含むような親ウィンドウをもつ。このフィールドは、ウィンドウの親を指す。

親ウィンドウはバッファーを表示せず、子ウィンドウ形成を除き、表示では少ししか役割を果たさない。Emacs Lispプログラムでからは、通常は親ウィンドウへのアクセスがない。Emacs Lispプログラムでは、実際にバッファーを表示するツリーの子ノードのウィンドウにたいして操作を行う。

hchild

vchild

これらのフィールドは、そのウィンドウの左端の子、上端の子を含む。子ウィンドウによりウィンドウが分割される場合はhchild、垂直に分割される場合はvchildが使用される。生きたウィンドウではhchild、vchild、bufferのいずれか1つだけが非nilとなる。

next

prev

そのウィンドウの次の兄弟と、前の兄弟。自身のグループ内でそのウィンドウが右端か下端なら、nextはnil。自身のグループ内でそのウィンドウが左端か上端なら、prevはnil。

left_col

そのウィンドウの左端を、そのフレームの最左列(列0)から相対的に数えた列数。

top_line

そのウィンドウの上端を、そのフレームの最上行(行0)から相対的に数えた行数。

total_cols

total_lines

列数と行数で数えた、そのウィンドウの幅と高さ。幅にはスクロールバーとフリンジ、および/または(もしあれば)ウィンドウ右側のセパレーターラインが含まれる。

buffer

そのウィンドウが表示しているバッファー。

start

そのウィンドウ内に表示されるバッファーで、ウィンドウに最初に表示される文字の位置を指すマーカー。

pointm

これは、そのウィンドウが選択されているときの、カレントバッファーのポイント値。選択されていなければ、前の値が保たれる。

force_start

このフラグが非nilなら、Lispプログラムによりそのウィンドウが明示的にスクロールされたことを示す。これはポイントがスクリーン外の場合の、次回再表示に影響を与える。影響とは、ポイント周辺のテキストを表示するためにウィンドウをスクロールするかわりに、スクリーン上にある位置にポイントを移動するというものである。

frozen_window_start_p

このフィールドは再表示にたいして、たとえポイントが不可視になったとしても、そのウィンドウのstartを変更するべきではないことを示すために、一時的に1にセットされる。

start_at_line_beg

非nilは、startのカレント値が、そのウィンドウ選択時に先頭行だったことを意味する。

use_time

これは、そのウィンドウが最後に選択された時刻である。関数get-lru-windowはこの値を使用する。

sequence_number

そのウィンドウ作成時に割り当てられた一意な番号。

last_modified

前回のそのウィンドウの再表示完了時の、そのウィンドウのバッファーのmodiffフィールド。

last_overlay_modified

前回のそのウィンドウの再表示完了時の、そのウィンドウのバッファーのoverlay_modiffフィールド。

last_point

前回のそのウィンドウの再表示完了時の、そのウィンドウのバッファーのポイント値。

last_had_star

A non-nil value means the window’s buffer was modified when the window was last updated.

vertical_scroll_bar

そのウィンドウの垂直スクロールバー。

left_margin_cols

right_margin_cols

そのウィンドウの、左マージンと右マージンの幅。値nilはマージンがないことを意味する。

left_fringe_width

right_fringe_width

そのウィンドウの、左フリンジと右フリンジの幅。値nilとtは、フレームの値の使用を意味する。

fringes_outside_margins

非nil値は、ディスプレーマージン外側のフリンジ、それ以外ならフリンジはマージンとテキストの間にあることを意味する。

window_end_pos

これはzから、そのウィンドウのカレントマトリクス内の最後のグリフのバッファー位置を減じて算出される。この値は、window_end_validが非nilのときだけ有効である。

window_end_bytepos

window_end_posに対応するバイト位置。

window_end_vpos

window_end_posを含む行の、ウィンドウに相対的な垂直位置。

window_end_valid

このフィールドは、window_end_posが真に有効なら、非nil値にセットされる。これは重要な再表示が先に割り込んだ場合には、window_end_posを算出した表示がスクリーン上に出現しなくなるのでnilとなる。

cursor

そのウィンドウ内でカーソルがどこにあるかを記述する構造体。

last_cursor

完了した最後の表示でのcursorの値。

phys_cursor

そのウィンドウのカーソルが物理的にどこにあるかを記述する構造体。

phys_cursor_type

phys_cursor_height

phys_cursor_width

そのウィンドウの最後の表示での、カーソルのタイプ、高さ、幅。

phys_cursor_on_p

このフィールドは、カーソルが物理的にオンなら非0。

cursor_off_p

非0はそのウィンドウのカーソルが、論理的にオフであることを意味する。これはカーソルの点滅に使用される。

last_cursor_off_p

このフィールドは最後の再表示時の、cursor_off_pの値を含む。

must_be_updated_p

これは、そのウィンドウを更新しなければならないとき、再表示の間1にセットされる。

hscroll

これは、そのウィンドウ内の表示が左へ水平スクロールされている列数。通常これは0。

vscroll

ピクセル単位での垂直スクロール量。通常これは0。

dedicated

そのウィンドウがそれのバッファー専用(dedicated)なら、非nil。

display_table

そのウィンドウのディスプレーテーブル、それが何も指定されていなければnil。

update_mode_line

非nilは、そのウィンドウのモードラインの更新が必要なことを意味する。

base_line_number

そのバッファーの特定の位置の行番号かnil。これは、モードラインでポイントの行番号を表示するために使用される。

base_line_pos

行番号が既知であるバッファー位置、それが知られていなければnil。これがバッファーなら、そのウィンドウがバッファーを表示するかぎり、行番号は表示されない。

column_number_displayed

そのウィンドウのモードラインに表示されているカレント列番号、列番号が表示されていなければnil。

current_matrix

desired_matrix

そのウィンドウのカレント、および望まれる表示を記述するグリフ。

E.8.3 プロセスの内部

プロセスのフィールドには以下が含まれます(完全なリストは、process.hのstruct Lisp_Processの定義を参照されたい):

name: プロセス名(文字列)。
command: そのプロセスの開始に使用された、コマンド引数を含むリスト。ネットワークプロセスとシリアルプロセスでは、そのプロセスが実行中ならnil、停止していたらt。
filter: そのプロセスから出力を受け取るために使用される関数。
sentinel: そのプロセスの状態が変化したら常に呼び出される関数。
buffer: そのプロセスに関連付けられたバッファー。
pid: オペレーティングシステムのプロセスID(整数)。ネットワークプロセスやシリアルプロセスのような疑似プロセスでは、値0を使用する。
childp: フラグで、もし実際に子プロセスならt。ネットワークプロセスやシリアルプロセスでは、make-network-processまたはmake-serial-processにもとづくplist。
mark: そのプロセスからの出力から、バッファーに挿入された終端位置を示すマーカー。常にではないが、これはしばしばバッファー終端である。
kill_without_query: これが非0なら、そのプロセス実行中にEmacsをkillしても、そのプロセスをkillすることにたいして確認を求めない。
raw_status: システムコールwaitがリターンする、rawプロセス状態。
status: process-statusがリターンするようなプロセス状態。
tick
update_tick: これら2つのフィールドが等しくないなら、センチネル実行またはプロセスバッファーへのメッセージ挿入により、そのプロセスの状態変更は報告される必要がある。
pty_flag: そのサブプロセスがptyを使用して対話する場合は非nil。パイプを使用する場合にはnil。
infd: そのプロセスからの入力にたいする、ファイルデゥクリプター。
outfd: そのプロセスへの出力にたいする、ファイルデゥクリプター。
tty_name: そのサブプロセスが使用する端末の名前、またはパイプを使用する場合はnil。
decode_coding_system: そのプロセスからの入力のデコーディングにたいするコーディングシステム。
decoding_buf: デコーディング用の作業バッファー。
decoding_carryover: デコーディングでのキャリーオーバーのサイズ。
encode_coding_system: そのプロセスからの出力のエンコーディングにたいするコーディングシステム。
encoding_buf: エンコーディング用の作業バッファー。
inherit_coding_system_flag: プロセス出力のデコードに使用されるコーディングシステムから、プロセスバッファーのcoding-systemをセットするフラグ。
type: プロセスのタイプを示すreal、network、serialいずれかのシンボル。

E.9 Cの整数型

以下はEmacsのCソースコード内で、整数タイプを使用する際のガイドラインです。これらのガイドラインはときに相反するアドバイスを与えることがありますが、一般的な常識に沿ったものがアドバイスです。

任意の制限の使用を避ける。たとえば、sの長さをintの範囲に収めることが要求されるのでなければ、int len = strlen (s);を使用しないこと。
Do not assume that signed integer arithmetic wraps around on overflow. This is no longer true of Emacs porting targets: signed integer overflow has undefined behavior in practice, and can dump core or even cause earlier or later code to behave illogically. Unsigned overflow does wrap around reliably, modulo a power of two.
符号なしタイプと符号付きタイプを組み合わせるとコードが混乱するので、符号なしタイプより符号付きタイプを優先すること。他のガイドラインの多くはタイプが符号付きだとみなしている。符号なしタイプを要する稀なケースでは、符号付きの符号なし版(ptrdiff_tのかわりにsize_t、intptr_tのかわりにuintptr_t)にたいして同様のアドバイスを適用できる。
Prefer int for Emacs character codes, in the range 0 .. 0x3FFFFF. More generally, prefer int for integers known to be in int range, e.g., screen column counts.
サイズ(たとえばすべての個別のCオブジェクトの最大サイズや、すべてのC配列の最大要素数にバインドされる整数)にたいしては、ptrdiff_tを優先すること。これは符号付きタイプにたいする、Emacsの一般的な優先事項である。ptrdiff_tの使用によりオブジェクトはPTRDIFF_MAXに制限されるが、より大きいオブジェクトはポインター減算を破壊するかもしれず、結局のところ問題を起こす可能性があるので、これは一方的に制限を課すものではない。
Avoid ssize_t except when communicating to low-level APIs that have ssize_t-related limitations. Although it’s equivalent to ptrdiff_t on typical platforms, ssize_t is occasionally narrower, so using it for size-related calculations could overflow. Also, ptrdiff_t is more ubiquitous and better-standardized, has standard printf formats, and is the basis for Emacs’s internal size-overflow checking. When using ssize_t, please note that POSIX requires support only for values in the range -1 .. SSIZE_MAX.
ポインターの内部表現や、与えられた任意のタイミングで存在可能なオブジェクト数や割り当て可能な総バイト数にのみバインドされる整数には、intptr_tを優先すること。現在のことこEmacsはintptr_tの使用したほうがよいときに、別のタイプを使用する場合がある。現在のEmacsのカレント移植先にたいして未修正でコードが動作するので、これの修正の優先度は低い。
Emacs Lispのfixnumへの変換や逆変換を表す値では、fixnum演算がEMACS_INTにもとづくので、Emacsで定義されたタイプEMACS_INTを優先すること。
(ファイルサイズやエポック以降の経過秒数等の)システム値を表す際は、(off_tやtime_t等の)システムタイプを優先すること。安全だと解っていなければ、システムタイプが符号付きだと仮定してはならない。たとえばoff_tは常に符号付きだが、time_tは符号付きである必要はない。
printf族の関数を使用してプリントされ得る任意の符号付き整数であるかもしれない値を表す場合は、Emacsの定義タイプprintmax_tを優先すること。
任意の符号付き整数であるかもしれない値を表す場合は、intmax_tを優先すること。
Prefer bool, false and true for booleans. Using bool can make programs easier to read and a bit faster than using int. Although it is also OK to use int, 0 and 1, this older style is gradually being phased out. When using bool, respect the limitations of the replacement implementation of bool, as documented in the source file lib/stdbool.in.h. In particular, boolean bitfields should be of type bool_bf, not bool, so that they work correctly even when compiling Objective C with standard GCC.
ビットフィールドでは、intは可搬性に劣るので、intよりunsigned intかsigned intを優先すること。単一ビットのビットフィールドの値は0か1なので、unsigned intかbool_bfを使用すること。

Appendix F 標準的なエラー

以下は、標準的なEmacsにおけるより重要なエラーシンボルを概念別にグループ分けしたリストです。このリストには各シンボルのメッセージと、そのエラーを発生し得る方法へのクロスリファレンスが含まれています。

これらのエラーシンボルはそれぞれ、親となるエラー条件のセットを、シンボルのリストとして保持します。通常このリストには、そのエラーシンボル自身と、シンボルerrorが含まれます。このリストは、errorより狭義ですが単一のエラーシンボルより広義であるような、中間的なクラス分けのための追加シンボルを含む場合があります。たとえば、ファイルアクセスでのすべてのエラーは、条件file-errorをもちます。ここでわたしたちが、特定のエラーシンボルにたいする追加エラー条件に言及していなければ、それがないことを意味しています。

特別な例外として、エラーシンボルquitは、quitはエラーとみなされないので、コンディションerrorをもっていません。

これらのエラーシンボルのほとんどは、C(主にdata.c)で定義されていますが、いくつかはLispで定義されています。たとえばファイルuserlock.elでは、file-lockedとfile-supersessionのエラーが定義されています。Emacsとともに配布される専門的なLispライブラリーのいくつかは、それら自身のエラーシンボルを定義しています。それらのすべてをここでリストはしません。

エラーの発生とそれを処理する方法については、エラーを参照してください。

error: メッセージは‘error’。エラーを参照のこと。
quit: メッセージは‘Quit’。quitを参照のこと。
args-out-of-range: メッセージは‘Args out of range’。これはシーケンス、バッファー、その他コンテナー風オブジェクトの範囲を超えた要素へのアクセスを試みたときに発生する。シーケンス、配列、ベクターとテキストを参照されたい。
arith-error: メッセージは‘Arithmetic error’。これは0による整数除算を試みたときに発生する。数値の変換と算術演算を参照されたい。
beginning-of-buffer: メッセージは‘Beginning of buffer’。文字単位の移動を参照のこと。
buffer-read-only: メッセージは‘Buffer is read-only’。読み取り専用のバッファーを参照のこと。
circular-list: メッセージは‘List contains a loop’。これは循環構造に遭遇時に発生する。循環オブジェクトの読み取り構文を参照のこと。
cl-assertion-failed: メッセージは‘Assertion failed’。これはcl-assertマクロのテスト失敗時に発生する。Assertions in Common Lisp Extensionsを参照のこと。
coding-system-error: メッセージは‘Invalid coding system’。Lispでのコーディングシステムを参照のこと。
cyclic-function-indirection: メッセージは‘Symbol's chain of function indirections contains a loop’。See section シンボル関数インダイレクションを参照のこと。
cyclic-variable-indirection: メッセージは‘Symbol's chain of variable indirections contains a loop’。See section 変数のエイリアスを参照のこと。
dbus-error: メッセージは‘D-Bus error’。これはEmacsがD-Busサポートつきでコンパイルされたときだけ定義される。Errors and Events in D-Bus integration in Emacsを参照のこと。
end-of-buffer: メッセージは‘End of buffer’。文字単位の移動を参照のこと。
end-of-file: メッセージは‘End of file during parsing’。これはファイルI/OではなくLispリーダーに属するので、file-errorのサブカテゴリーではないことに注意のこと。入力関数を参照されたい。
file-already-exists: これはfile-errorのサブカテゴリーである。ファイルの書き込みを参照のこと。
file-date-error: これはfile-errorのサブカテゴリーである。これはcopy-fileを試行して、出力ファイルの最終変更時刻のセットに失敗したときに発生する。ファイルの名前と属性の変更を参照のこと。
file-error: これのエラーメッセージは通常、エラー条件file-errorが与えられたときはデータアイテムだけから構築されるので、これのエラー文字列とサブカテゴリーはここにリストしない。つまりエラー文字列は特に関連しない。しかしこれらのエラーシンボルはerror-messageプロパティをもち、何もデータが与えられなければ、error-messageが使用される。ファイルを参照のこと。
file-missing: This is a subcategory of file-error. It occurs when an operation attempts to act on a file that is missing. See section ファイルの名前と属性の変更.
compression-error: これは圧縮ファイルの処理の問題を起因とする、file-errorのサブカテゴリーである。プログラムがロードを行う方法を参照のこと。
file-locked: これはfile-errorのサブカテゴリーである。ファイルのロックを参照のこと。
file-supersession: これはfile-errorのサブカテゴリーである。バッファーの変更 Timeを参照のこと。
file-notify-error: これはfile-errorのサブカテゴリーである。ファイル変更による通知を参照のこと。
ftp-error: これはftpを使用したリモートファイルへのアクセスの問題を起因とする、file-errorのサブカテゴリーである。Remote Files in The GNU Emacs Manualを参照のこと。
invalid-function: メッセージは‘Invalid function’。シンボル関数インダイレクションを参照のこと。
invalid-read-syntax: メッセージは‘Invalid read syntax’。プリント表現と読み取り構文を参照のこと。
invalid-regexp: メッセージは‘Invalid regexp’。正規表現を参照のこと。
mark-inactive: メッセージは‘The mark is not active now’。マークを参照のこと。
no-catch: メッセージは‘No catch for tag’。明示的な非ローカル脱出: catchとthrowを参照のこと。
scan-error: The message is ‘Scan error’. This happens when certain syntax-parsing functions find invalid syntax or mismatched parentheses. Conventionally raised with three argument: a human-readable error message, the start of the obstacle that cannot be moved over, and the end of the obstacle. See section バランスのとれたカッコを越えた移動, and See section 式のパース.
search-failed: メッセージは‘Search failed’。検索とマッチングを参照のこと。
setting-constant: The message is ‘Attempt to set a constant symbol’. This happens when attempting to assign values to nil, t, most-positive-fixnum, most-negative-fixnum, and keyword symbols. It also happens when attempting to assign values to enable-multibyte-characters and some other symbols whose direct assignment is not allowed for some reason. See section 変更不可な変数.
text-read-only: メッセージは‘Text is read-only’。これはbuffer-read-onlyのサブカテゴリーである。特殊な意味をもつプロパティを参照のこと。
undefined-color: メッセージは‘Undefined color’、カラー名を参照のこと。
user-error: メッセージは空文字列。エラーをシグナルする方法を参照のこと。
user-search-failed: This is like ‘search-failed’, but doesn’t trigger the debugger, like ‘user-error’. See section エラーをシグナルする方法, and See section 検索とマッチング. This is used for searching in Info files, See Search Text in Info.
void-function: メッセージは‘Symbol's function definition is void’。関数セルの内容へのアクセスを参照のこと。
void-variable: メッセージは‘Symbol's value as variable is void’。変数の値へのアクセスを参照のこと。
wrong-number-of-arguments: The message is ‘Wrong number of arguments’. See section 引数リストのその他機能.
wrong-type-argument: メッセージは‘Wrong type argument’。型のための述語を参照のこと。

Appendix G 標準的なキーマップ

このセクションでは、より一般的なキーマップをリストします。これらの多くはEmacsの初回起動時に存在しますが、それらのいくつかは各機能へのアクセス時にロードされます。

他にもより特化された、多くのキーマップがあります。それらは特にメジャーモードやマイナーモードに関連付けられています。ミニバッファーはいくつかのキーマップを使用します(補完を行うミニバッファーコマンドを参照)。キーマップの詳細については、キーマップを参照してください。

2C-mode-map: プレフィクスC-x 6のサブコマンドにたいするsparseキーマップ。
Two-Column Editing in The GNU Emacs Manualを参照のこと。
abbrev-map: プレフィクスC-x aのサブコマンドにたいするsparseキーマップ。
Defining Abbrevs in The GNU Emacs Manualを参照のこと。
button-buffer-map: バッファーを含むバッファーに有用なsparseキーマップ。
これを親キーマップとして使用したいと思うかもしれない。ボタンを参照のこと。
button-map: ボタンにより使用されるsparseキーマップ。
ctl-x-4-map: プレフィックスC-x 4のサブコマンドのsparseキーマップである。
ctl-x-5-map: プレフィックスC-x 5のサブコマンドのsparseキーマップである。
ctl-x-map: C-xコマンドにたいする完全なキーマップ。
ctl-x-r-map: プレフィクスC-x rのサブコマンドにたいするsparseキーマップ。
Registers in The GNU Emacs Manualを参照のこと。
esc-map: A full keymap for ESC (or Meta) commands.
facemenu-keymap: プレフィクスキーM-oにたいして使用されるsparseキーマップ。
function-key-map: すべてのlocal-function-key-mapのインスタンスの親キーマップ(local-function-key-mapを参照せよ)。
global-map: デフォルトのグローバルキーバインディングを含む完全なキーマップ。
モードでこのグローバルマップを変更しないこと。
goto-map: プレフィクスキーM-gにたいして使用されるsparseキーマップ。
help-map: ヘルプ文字C-hに後続するキーにたいするsparseキーマップ。
ヘルプ関数を参照のこと。
Helper-help-map: ヘルプユーティリティパッケージにより使用される完全なキーマップ。
これは値セルと関数セルに同じキーマップをもつ。
input-decode-map: キーパッドとファンクションキーの変換にたいするキーマップ。
存在しなければ空のsparseキーマップを含む。イベントシーケンス変換のためのキーマップを参照のこと。
key-translation-map: キー変換にたいするキーマップ。local-function-key-mapと異なり、これは通常のキーバインディングをオーバーライドする。イベントシーケンス変換のためのキーマップを参照のこと。
kmacro-keymap: プレフィクス検索C-x C-kに後続するキーにたいするsparseキーマップ。
Keyboard Macros in The GNU Emacs Manualヲ参照のこと。
local-function-key-map: キーシーケンスを優先する代替えへと変換するキーマップ。
存在しなければ空のsparseキーマップが含まれる。イベントシーケンス変換のためのキーマップを参照のこと。
menu-bar-file-menu
menu-bar-edit-menu
menu-bar-options-menu
global-buffers-menu-map
menu-bar-tools-menu
menu-bar-help-menu: これらのキーマップはメニューバー内の、メインとなるトップレベルメニューを表示する。
これらのいくつかはサブメニューを含む。たとえばEditメニューはmenu-bar-search-menuを含む等。メニューバー Barを参照のこと。
minibuffer-inactive-mode-map: ミニバッファーが非アクティブ時に使用される完全なキーマップ。
Editing in the Minibuffer in The GNU Emacs Manualを参照のこと。
mode-line-coding-system-map
mode-line-input-method-map
mode-line-column-line-number-mode-map: これらのキーマップはモードライン内の種々のエリアを制御する。
モードラインのフォーマットを参照のこと。
mode-specific-map: C-cに後続する文字にたいするキーマップ。これはグローバルキーマップ内にあることに注意。これは実際にはモード固有のものではない。プフィクスキーC-cの使用方法を主に記述するC-h b (display-bindings)内で有益なので、この名前が選ばれた。
mouse-appearance-menu-map: S-mouse-1キーにたいして使用されるsparseキーマップ。
mule-keymap: プレフィクスキーC-x RETにたいして使用されるグローバルキーマップ。
narrow-map: プレフィクスC-x nのサブコマンドにたいするsparseキーマップ。
prog-mode-map: Progモードにより使用されるキーマップ。
基本的なメジャーモードヲ参照のこと。
query-replace-map
multi-query-replace-map: query-replaceでの応答と、それに関連するコマンド、y-or-n-pとmap-y-or-n-pにたいしても使用されるsparseキーマップ。このマップを使用する関数はプレフィクスキーを使用せず、一度に1つのイベントを照会する。複数バッファーの置換では、multi-query-replace-mapがquery-replace-mapを拡張する。query-replace-mapを参照のこと。
search-map: 検索関連コマンドにたいしてグローバルバインディングを提供する、sparseキーマップ。
special-mode-map: Specialモードにより使用されるキーマップ。
基本的なメジャーモードを参照のこと。
tool-bar-map: ツールバーのコンテンツを定義するキーマップ。
ツールバーを参照のこと。
universal-argument-map: C-u処理中に使用されるsparseキーマップ。
プレフィクスコマンド引数を参照のこと。
vc-prefix-map: プレフィクスキーC-x vにたいして使用されるグローバルキーマップ。
x-alternatives-map: グラフィカルなフレームでの特定キーのマップに使用されるsparseキーマップ。
関数x-setup-function-keysはこれを使用する。

Appendix H 標準的なフック

以下は、EMacsで適切なタイミングで呼び出す関数を提供するための、いくつかのフック関数のリストです。

これらの変数のほとんどは、‘-hook’で始まる名前をもちます。これらはノーマルフック(normal hooks)と呼ばれ、run-hooksにより実行されます。そのようなフックの値は関数のリストです。これらの関数は引数なしで呼び出され、値は完全にに無視されます。そのようなフック上に新たに関数を配置するための推奨は、add-hookを呼び出す方法です。フック使用についての詳細は、フックを参照してください。

‘-functions’で終わる名前の変数は、通常はアブノーマルフック(abnormal hooks)です(古いコードには推奨されない‘-hooks’サフィクスを使用するものもある)。これらの値は関数のリストですが、これらの関数は特殊な方法で呼び出されます(引数を渡されたりリターン値が使用される)。‘-function’で終わる名前の変数は、値として単一の関数をもちます。

以下のリストはすべてを網羅したリストではなく、より一般的なフックだけをカバーしています。たとえばメジャーモードはそれぞれ、‘modename-mode-hook’という名前のフックを定義します。メジャーモードは自身が行う最後のこととして、run-mode-hooksでこのノーマルフックを実行します。モードフックを参照してください。ほとんどのマイナーモードにもフックがあります。

特別な機能により、あるファイルがロードされたときに評価する式を指定できます(ロードのためのフックを参照)。この機能は正確にはフックではありませんが、同様のことを行います。

activate-mark-hook
deactivate-mark-hook: マークを参照のこと。
after-change-functions
before-change-functions
first-change-hook: フックの変更を参照のこと。
after-change-major-mode-hook
change-major-mode-after-body-hook: モードフックを参照のこと。
after-init-hook
before-init-hook
emacs-startup-hook
window-setup-hook: initファイルを参照のこと。
after-insert-file-functions
write-region-annotate-functions
write-region-post-annotation-function: ファイルのフォーマット変換を参照のこと。
after-make-frame-functions
before-make-frame-hook: フレームの作成を参照のこと。
after-save-hook
before-save-hook
write-contents-functions
write-file-functions: バッファーの保存を参照のこと。
after-setting-font-hook: Hook run after a frame’s font changes.
auto-save-hook: See section 自動保存を参照のこと。
before-hack-local-variables-hook
hack-local-variables-hook: ファイルローカル変数を参照のこと。
buffer-access-fontify-functions: テキストプロパティのlazyな計算を参照のこと。
buffer-list-update-hook: バッファーリスト変更時に実行されるフック(バッファーリストを参照)。
buffer-quit-function: Function to call to quit the current buffer.
change-major-mode-hook: バッファーローカルなバインディングの作成と削除を参照のこと。
command-line-functions: コマンドライン引数を参照のこと。
delayed-warnings-hook: コマンドループはpost-command-hook(以下参照)の直後にこれを実行する。
focus-in-hook
focus-out-hook: 入力のフォーカスを参照のこと。
delete-frame-functions: フレームの削除を参照のこと。
delete-terminal-functions: 複数の端末を参照のこと。
pop-up-frame-function
split-window-preferred-function: バッファー表示の追加オプションを参照のこと。
echo-area-clear-hook: エコーエリアのカスタマイズを参照のこと。
find-file-hook
find-file-not-found-functions: ファイルをvisitする関数を参照のこと。
font-lock-extend-after-change-region-function: バッファー変更後のリージョンのフォント化を参照のこと。
font-lock-extend-region-functions: 複数行のFont Lock構造を参照のこと。
font-lock-fontify-buffer-function
font-lock-fontify-region-function
font-lock-mark-block-function
font-lock-unfontify-buffer-function
font-lock-unfontify-region-function: Font Lockのその他の変数を参照のこと。
fontification-functions: Automatic Face Assignmentを参照のこと。
frame-auto-hide-function: ウィンドウのquitを参照のこと。
kill-buffer-hook
kill-buffer-query-functions: バッファーのkillを参照のこと。
kill-emacs-hook
kill-emacs-query-functions: Emacsのkillを参照のこと。
menu-bar-update-hook: メニューバー Barを参照のこと。
minibuffer-setup-hook
minibuffer-exit-hook: ミニバッファー、その他の事項を参照のこと。
mouse-leave-buffer-hook: マウスコマンドでのウィンドウ切り替え時に実行されるフック。
mouse-position-function: マウスの位置を参照のこと。
prefix-command-echo-keystrokes-functions: An abnormal hook run by prefix commands (such as C-u) which should return a string describing the current prefix state. For example, C-u produces ‘C-u-’ and ‘C-u 1 2 3-’. Each hook function is called with no arguments and should return a string describing the current prefix state, or nil if there’s no prefix state. See section プレフィクスコマンド引数.
prefix-command-preserve-state-hook: Hook run when a prefix command needs to preserve the prefix by passing the current prefix command state to the next command. For example, C-u needs to pass the state to the next command when the user types C-u - or follows C-u with a digit.
pre-redisplay-functions: Hook run in each window just before redisplaying it. See section 強制的な再表示.
post-command-hook
pre-command-hook: コマンドループの概要を参照のこと。
post-gc-hook: ガーベージコレクションを参照のこと。
post-self-insert-hook: キーマップとマイナーモードを参照のこと。
suspend-hook
suspend-resume-hook
suspend-tty-functions
resume-tty-functions: Emacsのサスペンドを参照のこと。
syntax-begin-function
syntax-propertize-extend-region-functions
syntax-propertize-function
font-lock-syntactic-face-function: 構文的なFont Lockおよび構文プロパティを参照されたい。
temp-buffer-setup-hook
temp-buffer-show-function
temp-buffer-show-hook: 一時的な表示を参照のこと。
tty-setup-hook: 端末固有の初期化を参照のこと。
window-configuration-change-hook
window-scroll-functions
window-size-change-functions: ウィンドウのスクロールと変更のためのフックを参照のこと。

Index

Jump to:	" # $ % & ' ( ) * + , - . / 1 2 3 ; < = > ? @ [ \ ] ^ ` \| A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

	Index Entry	Section

"
	‘`"`’ in printing	19.5 出力関数
	‘`"`’ in strings	2.3.8.1 文字列の構文

#
	‘`##`’ read syntax	2.3.4 シンボル型
	‘`#$`’	17.3 ドキュメント文字列とコンパイル
	‘`#'`’ syntax	13.7 無名関数
	‘`#(`’ read syntax	2.3.8.4 文字列内のテキストプロパティ
	‘`#:`’ read syntax	2.3.4 シンボル型
	‘`#@count`’	17.3 ドキュメント文字列とコンパイル
	‘`#n#`’ read syntax	2.5 循環オブジェクトの読み取り構文
	‘`#n=`’ read syntax	2.5 循環オブジェクトの読み取り構文
	‘`#^`’ read syntax	2.3.10 文字テーブル型

$
	‘`$`’ in display	39.3 切り詰め
	‘`$`’ in regexp	34.3.1.1 正規表現内の特殊文字

%
	`%`	3.6 算術演算
	‘`%`’ in format	4.7 文字列のフォーマット

&
	‘`&`’ in replacement	34.6.1 マッチしたテキストの置換
	`&optional`	13.2.3 引数リストのその他機能
	`&rest`	13.2.3 引数リストのその他機能

'
	‘`'`’ for quoting	10.3 クォート

(
	‘`(`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`(…)`’ in lists	2.3.6 コンスセルとリスト型
	‘`(?:`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造

)
	‘`)`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造

*
	`*`	3.6 算術演算
	‘`*`’ in `interactive`	21.2.1 `interactive`の使用
	‘`*`’ in regexp	34.3.1.1 正規表現内の特殊文字
	`scratch`	23.2.2 Emacsがメジャーモードを選択する方法

+
	`+`	3.6 算術演算
	‘`+`’ in regexp	34.3.1.1 正規表現内の特殊文字

,
	`, (with backquote)`	10.4 バッククォート
	`,@ (with backquote)`	10.4 バッククォート

-
	`-`	3.6 算術演算
	`--disable-build-details` option to `configure`	E.1 Emacsのビルド
	`--enable-locallisppath` option to `configure`	E.1 Emacsのビルド
	–enable-profiling option of configure	18.5 プロファイリング

.
	‘`.`’ in lists	2.3.6.2 ドットペア表記
	‘`.`’ in regexp	34.3.1.1 正規表現内の特殊文字
	`.emacs`	40.1.2 initファイル

/
	`/`	3.6 算術演算
	`/=`	3.4 数値の比較
	`/dev/tty`	38.19 シリアルポートとの対話

1
	`1+`	3.6 算術演算
	`1-`	3.6 算術演算
	`1value`	18.4 カバレッジテスト

2
	`2C-mode-map`	22.6 プレフィクスキー
	2D box	39.12.1 フェイスの属性

3
	3D box	39.12.1 フェイスの属性

;
	‘`;`’ in comment	2.2 コメント

<
	`<`	3.4 数値の比較
	`<=`	3.4 数値の比較

=
	`=`	3.4 数値の比較

>
	`>`	3.4 数値の比較
	`>=`	3.4 数値の比較

?
	‘`?`’ in character constant	2.3.3.1 基本的な文字構文
	`?` in minibuffer	20.2 ミニバッファーでのテキスト文字列の読み取り
	‘`?`’ in regexp	34.3.1.1 正規表現内の特殊文字

@
	‘`@`’ in `interactive`	21.2.1 `interactive`の使用

[
	‘`[`’ in regexp	34.3.1.1 正規表現内の特殊文字
	[…] (Edebug)	18.2.15.2 仕様リスト

\
	‘`\`’ in character constant	2.3.3.2 一般的なエスケープ構文
	‘`\`’ in display	39.3 切り詰め
	‘`\`’ in printing	19.5 出力関数
	‘`\`’ in regexp	34.3.1.1 正規表現内の特殊文字
	‘`\`’ in replacement	34.6.1 マッチしたテキストの置換
	‘`\`’ in strings	2.3.8.1 文字列の構文
	‘`\`’ in symbols	2.3.4 シンボル型
	‘`\'`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\<`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\=`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\>`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\a`’	2.3.3.1 基本的な文字構文
	‘`\b`’	2.3.3.1 基本的な文字構文
	‘`\b`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\B`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\e`’	2.3.3.1 基本的な文字構文
	‘`\f`’	2.3.3.1 基本的な文字構文
	‘`\n`’	2.3.3.1 基本的な文字構文
	‘`\n`’ in print	19.6 出力に影響する変数
	‘`\n`’ in replacement	34.6.1 マッチしたテキストの置換
	‘`\r`’	2.3.3.1 基本的な文字構文
	‘`\s`’	2.3.3.1 基本的な文字構文
	‘`\s`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\S`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\t`’	2.3.3.1 基本的な文字構文
	‘`\v`’	2.3.3.1 基本的な文字構文
	‘`\w`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\W`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\_<`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘`\_>`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造
	‘\`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造

]
	‘`]`’ in regexp	34.3.1.1 正規表現内の特殊文字

^
	‘`^`’ in `interactive`	21.2.1 `interactive`の使用
	‘`^`’ in regexp	34.3.1.1 正規表現内の特殊文字

`
	`	10.4 バッククォート
	‘ (list substitution)	10.4 バッククォート

\|
	‘`\|`’ in regexp	34.3.1.3 正規表現内のバッククラッシュ構造

A
	abbrev	36 abbrevとabbrev展開
	abbrev properties	36.6 abbrevプロパティー
	abbrev table properties	36.7 abbrevテーブルのプロパティー
	abbrev tables	36.1 abbrevテーブル
	abbrev tables in modes	23.2.1 メジャーモードの慣習
	`abbrev-all-caps`	36.4 略語の照会と展開
	`abbrev-expand-function`	36.4 略語の照会と展開
	`abbrev-expansion`	36.4 略語の照会と展開
	`abbrev-file-name`	36.3 ファイルへのabbrevの保存
	`abbrev-get`	36.6 abbrevプロパティー
	`abbrev-insert`	36.4 略語の照会と展開
	`abbrev-map`	Appendix G 標準的なキーマップ
	`abbrev-minor-mode-table-alist`	36.5 標準的なabbrevテーブル
	`abbrev-prefix-mark`	36.4 略語の照会と展開
	`abbrev-put`	36.6 abbrevプロパティー
	`abbrev-start-location`	36.4 略語の照会と展開
	`abbrev-start-location-buffer`	36.4 略語の照会と展開
	`abbrev-symbol`	36.4 略語の照会と展開
	`abbrev-table-get`	36.7 abbrevテーブルのプロパティー
	`abbrev-table-name-list`	36.1 abbrevテーブル
	`abbrev-table-p`	36.1 abbrevテーブル
	`abbrev-table-put`	36.7 abbrevテーブルのプロパティー
	`abbreviate-file-name`	25.9.3 ディレクトリーの名前
	abbreviated file names	25.9.3 ディレクトリーの名前
	abbrevs, looking up and expanding	36.4 略語の照会と展開
	`abbrevs-changed`	36.3 ファイルへのabbrevの保存
	abnormal hook	23.1 フック
	`abort-recursive-edit`	21.13 再帰編集
	aborting	21.13 再帰編集
	`abs`	3.4 数値の比較
	absolute edges	29.3.1 Frame Layout
	absolute file name	25.9.2 絶対ファイル名と相対ファイル名
	absolute frame edges	29.3.1 Frame Layout
	absolute frame position	29.3.1 Frame Layout
	absolute position	29.3.1 Frame Layout
	accept input from processes	38.9.4 プロセスからの出力を受け入れる
	`accept-change-group`	32.29 グループのアトミックな変更
	`accept-process-output`	38.9.4 プロセスからの出力を受け入れる
	access control list	25.6.5 拡張されたファイル属性
	access minibuffer contents	20.12 ミニバッファーのコンテンツ
	`access-file`	25.6.1 アクセシビリティのテスト
	accessibility of a file	25.6.1 アクセシビリティのテスト
	accessible portion (of a buffer)	30.4 ナローイング
	`accessible-keymaps`	22.16 キーマップのスキャン
	accessing documentation strings	24.2 ドキュメント文字列へのアクセス
	accessing hash tables	8.2 ハッシュテーブルへのアクセス
	accessing plist properties	5.9.2 プロパティリストと外部シンボル
	ACL entries	25.6.5 拡張されたファイル属性
	`acos`	3.9 標準的な数学関数
	`action (button property)`	39.19.1 ボタンのプロパティ
	action alist, for `display-buffer`	28.13 表示するウィンドウの選択
	action function, for `display-buffer`	28.13 表示するウィンドウの選択
	`action, customization keyword`	15.4.4 型キーワード
	`activate-change-group`	32.29 グループのアトミックな変更
	`activate-mark-hook`	31.7 マーク
	active display table	39.22.3 アクティブなディスプレーテーブル
	active keymap	22.7 アクティブなキーマップ
	active keymap, controlling	22.9 アクティブなキーマップの制御
	`active-minibuffer-window`	20.11 ミニバッファーのウィンドウ
	`ad-activate`	13.11.4 古いdefadviceを使用するコードの改良
	`adaptive-fill-first-line-regexp`	32.13 Adaptive Fillモード
	`adaptive-fill-function`	32.13 Adaptive Fillモード
	`adaptive-fill-mode`	32.13 Adaptive Fillモード
	`adaptive-fill-regexp`	32.13 Adaptive Fillモード
	`add-face-text-property`	32.19.2 テキストプロパティの変更
	`add-function`	13.11.1 アドバイスを操作するためのプリミティブ
	`add-hook`	23.1.2 フックのセットSetting Hooks
	`add-name-to-file`	25.7 ファイルの名前と属性の変更
	`add-text-properties`	32.19.2 テキストプロパティの変更
	`add-to-history`	20.4 ミニバッファーのヒストリー
	`add-to-invisibility-spec`	39.6 不可視のテキスト
	`add-to-list`	5.5 リスト変数の変更
	`add-to-ordered-list`	5.5 リスト変数の変更
	`add-variable-watcher`	12.9 Running a function when a variable is changed.
	address field of register	2.3.6 コンスセルとリスト型
	`adjust-window-trailing-edge`	28.4 ウィンドウのリサイズ
	adjusting point	21.6 コマンド後のポイントの調整
	advertised binding	24.3 ドキュメント内でのキーバインディングの置き換え
	advice, add and remove	13.11.1 アドバイスを操作するためのプリミティブ
	`advice-add`	13.11.2 名前つき関数にたいするアドバイス
	`advice-eval-interactive-spec`	13.11.1 アドバイスを操作するためのプリミティブ
	`advice-function-mapc`	13.11.1 アドバイスを操作するためのプリミティブ
	`advice-function-member-p`	13.11.1 アドバイスを操作するためのプリミティブ
	`advice-mapc`	13.11.2 名前つき関数にたいするアドバイス
	`advice-member-p`	13.11.2 名前つき関数にたいするアドバイス
	`advice-remove`	13.11.2 名前つき関数にたいするアドバイス
	advices, porting from `defadvice`	13.11.4 古いdefadviceを使用するコードの改良
	advising functions	13.11 Emacs Lisp関数にたいするアドバイス
	advising named functions	13.11.2 名前つき関数にたいするアドバイス
	AEAD cipher	32.27 GnuTLS Cryptography
	`after-change-functions`	32.30 フックの変更
	`after-change-major-mode-hook`	23.2.6 モードフック
	`after-find-file`	25.1.2 visitのためのサブルーチン
	`after-init-hook`	40.1.2 initファイル
	`after-init-time`	40.1.1 要約: スタートアップ時のアクション順序
	`after-insert-file-functions`	25.13.3 漸次仕様
	`after-load-functions`	16.10 ロードのためのフック
	`after-make-frame-functions`	29.1 フレームの作成
	`after-revert-hook`	26.3 リバート
	`after-save-hook`	25.2 バッファーの保存
	`after-setting-font-hook`	Appendix H 標準的なフック
	`after-string (overlay property)`	39.9.2 オーバーレイのプロパティ
	alias, for coding systems	33.10.1 コーディングシステムの基本概念
	alias, for faces	39.12.6 フェイスを処理するための関数
	alias, for functions	13.4 関数の定義
	alias, for variables	12.15 変数のエイリアス
	alist	5.8 連想リスト
	alist vs. plist	5.9.1 プロパティリストと連想リスト
	`alist-get`	5.8 連想リスト
	`all-completions`	20.6.1 基本的な補完関数
	`all-threads`	37.1 Basic Thread Functions
	`alpha, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	alt characters	2.3.3.5 その他の文字修飾ビット
	alternatives, defining	21.2.4 コマンド候補からの選択
	amalgamating commands, and undo	32.9 アンドゥ
	`and`	11.3 条件の組み合わせ
	animation	39.17.10 マルチフレームのイメージ
	anonymous face	39.12 フェイス
	anonymous function	13.7 無名関数
	apostrophe for quoting	10.3 クォート
	`append`	5.4 コンスセルおよびリストの構築
	`append-to-file`	25.4 ファイルの書き込み
	`apply`	13.5 関数の呼び出し
	`apply`, and debugging	18.1.9 デバッガの内部
	`apply-partially`	13.5 関数の呼び出し
	applying customizations	15.5 カスタマイズの適用
	`apropos`	24.6 ヘルプ関数
	`aref`	6.3 配列を操作する関数
	`args, customization keyword`	15.4.2 複合型
	argument	13.1 関数とは?
	argument binding	13.2.3 引数リストのその他機能
	argument lists, features	13.2.3 引数リストのその他機能
	arguments for shell commands	38.2 shell引数
	arguments, interactive entry	21.2.1 `interactive`の使用
	arguments, reading	20 ミニバッファー
	`argv`	40.1.4 コマンドライン引数
	`arith-error` example	11.6.3.3 エラーを処理するコードの記述
	`arith-error` in division	3.6 算術演算
	arithmetic operations	3.6 算術演算
	arithmetic shift	3.8 ビット演算 on Integers
	array	6.2 配列
	array elements	6.3 配列を操作する関数
	`arrayp`	6.3 配列を操作する関数
	ASCII character codes	2.3.3 文字型
	ASCII control characters	39.22.1 通常の表示の慣習
	`ascii-case-table`	4.9 caseテーブル
	`aset`	6.3 配列を操作する関数
	`ash`	3.8 ビット演算 on Integers
	`asin`	3.9 標準的な数学関数
	`ask-user-about-lock`	25.5 ファイルのロック
	`ask-user-about-supersession-threat`	27.6 バッファーの変更 Time
	asking the user questions	20.7 Yes-or-Noによる問い合わせ
	`assoc`	5.8 連想リスト
	`assoc-default`	5.8 連想リスト
	`assoc-string`	4.5 文字および文字列の比較
	association list	5.8 連想リスト
	`assq`	5.8 連想リスト
	`assq-delete-all`	5.8 連想リスト
	asynchronous subprocess	38.4 非同期プロセスの作成
	`atan`	3.9 標準的な数学関数
	`atom`	5.2 リストのための述語
	atomic changes	32.29 グループのアトミックな変更
	atomic windows	28.20 Atomic Windows
	atoms	2.3.6 コンスセルとリスト型
	attributes of text	32.19 テキストのプロパティ
	Auto Fill mode	32.14 オートfill
	`auto-coding-alist`	33.10.5 デフォルトのコーディングシステム
	`auto-coding-functions`	33.10.5 デフォルトのコーディングシステム
	`auto-coding-regexp-alist`	33.10.5 デフォルトのコーディングシステム
	`auto-fill-chars`	32.14 オートfill
	`auto-fill-function`	32.14 オートfill
	`auto-hide-function, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`auto-hscroll-mode`	28.25 水平スクロール
	`auto-lower, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`auto-mode-alist`	23.2.2 Emacsがメジャーモードを選択する方法
	`auto-raise, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`auto-raise-tool-bar-buttons`	22.17.6 ツールバー
	`auto-resize-tool-bars`	22.17.6 ツールバー
	`auto-save-default`	26.2 自動保存
	`auto-save-file-name-p`	26.2 自動保存
	`auto-save-hook`	26.2 自動保存
	`auto-save-interval`	26.2 自動保存
	`auto-save-list-file-name`	26.2 自動保存
	`auto-save-list-file-prefix`	26.2 自動保存
	`auto-save-mode`	26.2 自動保存
	`auto-save-timeout`	26.2 自動保存
	`auto-save-visited-file-name`	26.2 自動保存
	auto-selection of window	28.27 Mouse Window Auto-selection
	`auto-window-vscroll`	28.24 割り合いによる垂直スクロール
	`autoload`	16.5 autoload
	autoload	16.5 autoload
	autoload cookie	16.5 autoload
	autoload cookie, and safe values of variable	12.12 ファイルローカル変数
	autoload errors	16.5 autoload
	autoload object	13.1 関数とは?
	autoload, when to use	16.5.1 When to Use Autoload
	`autoload-do-load`	16.5 autoload
	`autoloadp`	16.5 autoload
	automatic face assignment	39.12.7 フェイスの自動割り当て
	automatically buffer-local	12.11.1 バッファーローカル変数の概要

B
	`back-to-indentation`	32.17.6 インデントにもとづくモーションコマンド
	`background-color, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`background-mode, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	backing store	29.25 ディスプレー機能のテスト
	backquote (list substitution)	10.4 バッククォート
	backslash in character constants	2.3.3.2 一般的なエスケープ構文
	backslash in regular expressions	34.3.1.3 正規表現内のバッククラッシュ構造
	backslash in strings	2.3.8.1 文字列の構文
	backslash in symbols	2.3.4 シンボル型
	backspace	2.3.3.1 基本的な文字構文
	`backtrace`	18.1.9 デバッガの内部
	backtrace from emacsclient’s `--eval`	18.1.1 エラーによるデバッガへのエンター
	`backtrace-debug`	18.1.9 デバッガの内部
	`backtrace-frame`	18.1.9 デバッガの内部
	backtracking	18.2.15.3 仕様でのバックトレース
	backtracking and POSIX regular expressions	34.5 POSIX正規表現の検索
	backtracking and regular expressions	34.3.1.1 正規表現内の特殊文字
	backup file	26.1 ファイルのバックアップ
	backup files, rename or copy	26.1.2 リネームかコピーのどちらでバックアップするか?
	`backup-buffer`	26.1.1 バックアップファイルの作成
	`backup-by-copying`	26.1.2 リネームかコピーのどちらでバックアップするか?
	`backup-by-copying-when-linked`	26.1.2 リネームかコピーのどちらでバックアップするか?
	`backup-by-copying-when-mismatch`	26.1.2 リネームかコピーのどちらでバックアップするか?
	`backup-by-copying-when-privileged-mismatch`	26.1.2 リネームかコピーのどちらでバックアップするか?
	`backup-directory-alist`	26.1.1 バックアップファイルの作成
	`backup-enable-predicate`	26.1.1 バックアップファイルの作成
	`backup-file-name-p`	26.1.4 バックアップファイルの命名
	`backup-inhibited`	26.1.1 バックアップファイルの作成
	backups and auto-saving	26 バックアップと自動保存
	`backward-button`	39.19.5 ボタンのためのバッファーコマンド
	`backward-char`	30.2.1 文字単位の移動
	`backward-delete-char-untabify`	32.6 テキストの削除
	`backward-delete-char-untabify-method`	32.6 テキストの削除
	`backward-list`	30.2.6 バランスのとれたカッコを越えた移動
	`backward-prefix-chars`	35.5 モーションと構文
	`backward-sexp`	30.2.6 バランスのとれたカッコを越えた移動
	`backward-to-indentation`	32.17.6 インデントにもとづくモーションコマンド
	`backward-up-list`	30.2.6 バランスのとれたカッコを越えた移動
	`backward-word`	30.2.2 単語単位の移動
	`backward-word-strictly`	30.2.2 単語単位の移動
	`balance-windows`	28.4 ウィンドウのリサイズ
	`balance-windows-area`	28.4 ウィンドウのリサイズ
	balanced parenthesis motion	30.2.6 バランスのとれたカッコを越えた移動
	balancing parentheses	39.21 カッコの点滅
	balancing window sizes	28.4 ウィンドウのリサイズ
	`barf-if-buffer-read-only`	27.7 読み取り専用のバッファー
	base 64 encoding	32.25 Base 64エンコーディング
	base buffer	27.11 インダイレクトバッファー
	base coding system	33.10.1 コーディングシステムの基本概念
	base direction of a paragraph	39.26 双方向テキストの表示
	base for reading an integer	3.1 整数の基礎
	base location, package archive	41.4 パッケージアーカイブの作成と保守
	base remapping, faces	39.12.5 フェイスのリマップ
	`base64-decode-region`	32.25 Base 64エンコーディング
	`base64-decode-string`	32.25 Base 64エンコーディング
	`base64-encode-region`	32.25 Base 64エンコーディング
	`base64-encode-string`	32.25 Base 64エンコーディング
	basic code (of input character)	21.7.1 キーボードイベント
	basic faces	39.12.8 基本的なフェイス
	batch mode	40.17 batchモード
	`batch-byte-compile`	17.2 バイトコンパイル関数
	baud, in serial connections	38.19 シリアルポートとの対話
	`baud-rate`	40.14 端末の出力
	`beep`	39.23 ビープ
	before point, insertion	32.4 テキストの挿入
	`before-change-functions`	32.30 フックの変更
	`before-hack-local-variables-hook`	12.12 ファイルローカル変数
	`before-init-hook`	40.1.2 initファイル
	`before-init-time`	40.1.1 要約: スタートアップ時のアクション順序
	`before-make-frame-hook`	29.1 フレームの作成
	`before-revert-hook`	26.3 リバート
	`before-save-hook`	25.2 バッファーの保存
	`before-string (overlay property)`	39.9.2 オーバーレイのプロパティ
	beginning of line	30.2.4 テキスト行単位の移動
	beginning of line in regexp	34.3.1.1 正規表現内の特殊文字
	`beginning-of-buffer`	30.2.3 バッファー終端への移動
	`beginning-of-defun`	30.2.6 バランスのとれたカッコを越えた移動
	`beginning-of-defun-function`	30.2.6 バランスのとれたカッコを越えた移動
	`beginning-of-line`	30.2.4 テキスト行単位の移動
	bell	39.23 ビープ
	bell character	2.3.3.1 基本的な文字構文
	`benchmark.el`	18.5 プロファイリング
	benchmarking	18.5 プロファイリング
	`bidi-display-reordering`	39.26 双方向テキストの表示
	`bidi-find-overridden-directionality`	39.26 双方向テキストの表示
	`bidi-paragraph-direction`	39.26 双方向テキストの表示
	`bidi-paragraph-separate-re`	39.26 双方向テキストの表示
	`bidi-paragraph-start-re`	39.26 双方向テキストの表示
	`bidi-string-mark-left-to-right`	39.26 双方向テキストの表示
	bidirectional class of characters	33.6 文字のプロパティ
	bidirectional display	39.26 双方向テキストの表示
	bidirectional reordering	39.26 双方向テキストの表示
	big endian	38.20.1 データレイアウトの記述
	`binary coding system`	33.10.1 コーディングシステムの基本概念
	binary I/O in batch mode	19.3 入力関数
	`bindat-get-field`	38.20.2 バイトのunpackとpackのための関数
	`bindat-ip-to-string`	38.20.2 バイトのunpackとpackのための関数
	`bindat-length`	38.20.2 バイトのunpackとpackのための関数
	`bindat-pack`	38.20.2 バイトのunpackとpackのための関数
	`bindat-unpack`	38.20.2 バイトのunpackとpackのための関数
	binding arguments	13.2.3 引数リストのその他機能
	binding local variables	12.3 ローカル変数
	binding of a key	22.2 キーマップの基礎
	`bitmap-spec-p`	39.12.1 フェイスの属性
	bitmaps, fringe	39.13.4 フリンジのビットマップ
	bitwise arithmetic	3.8 ビット演算 on Integers
	`blink-cursor-alist`	29.4.3.9 カーソルのパラメーター
	`blink-matching-delay`	39.21 カッコの点滅
	`blink-matching-open`	39.21 カッコの点滅
	`blink-matching-paren`	39.21 カッコの点滅
	`blink-matching-paren-distance`	39.21 カッコの点滅
	`blink-paren-function`	39.21 カッコの点滅
	blinking parentheses	39.21 カッコの点滅
	`bobp`	32.1 ポイント周辺のテキストを調べる
	body height of a window	28.3 ウィンドウのサイズ
	body of a window	28.3 ウィンドウのサイズ
	body of function	13.2.1 ラムダ式の構成要素
	body size of a window	28.3 ウィンドウのサイズ
	body width of a window	28.3 ウィンドウのサイズ
	`bolp`	32.1 ポイント周辺のテキストを調べる
	`bool-vector`	6.7 ブールベクター
	`bool-vector-count-consecutive`	6.7 ブールベクター
	`bool-vector-count-population`	6.7 ブールベクター
	`bool-vector-exclusive-or`	6.7 ブールベクター
	`bool-vector-intersection`	6.7 ブールベクター
	`bool-vector-not`	6.7 ブールベクター
	`bool-vector-p`	6.7 ブールベクター
	`bool-vector-set-difference`	6.7 ブールベクター
	`bool-vector-subsetp`	6.7 ブールベクター
	`bool-vector-union`	6.7 ブールベクター
	Bool-vectors	6.7 ブールベクター
	boolean	1.3.2 `nil`と`t`
	`booleanp`	1.3.2 `nil`と`t`
	`border-color, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`border-width, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	bottom dividers	39.15 ウィンドウディバイダー
	`bottom-divider-width, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`bottom-visible, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	`boundp`	12.4 When a Variable is Void
	box diagrams, for lists	2.3.6.1 ボックスダイアグラムとしてのリストの描写
	break	18.1 Lispデバッガ
	breakpoints (Edebug)	18.2.6.1 Edebugのブレークポイント
	bucket (in obarray)	9.3 シンボルの作成とintern
	buffer	27 バッファー
	buffer boundaries, indicating	39.13.2 フリンジのインジケーター
	buffer contents	32 テキスト
	buffer file name	27.4 バッファーのファイル名
	buffer gap	27.13 バッファーのギャップ
	buffer input stream	19.2 入力ストリーム
	buffer internals	E.8.1 バッファーの内部
	buffer list	27.8 バッファーリスト
	buffer modification	27.5 バッファーの変更
	buffer names	27.3 バッファーの名前
	buffer output stream	19.4 出力ストリーム
	buffer portion as string	32.2 バッファーのコンテンツを調べる
	buffer position	30 ポジション
	buffer text notation	1.3.6 バッファーテキストの表記
	buffer, read-only	27.7 読み取り専用のバッファー
	`buffer-access-fontified-property`	32.19.7 テキストプロパティのlazyな計算
	`buffer-access-fontify-functions`	32.19.7 テキストプロパティのlazyな計算
	`buffer-auto-save-file-format`	25.13.2 ラウンドトリップ仕様
	`buffer-auto-save-file-name`	26.2 自動保存
	`buffer-backed-up`	26.1.1 バックアップファイルの作成
	`buffer-base-buffer`	27.11 インダイレクトバッファー
	`buffer-chars-modified-tick`	27.5 バッファーの変更
	`buffer-disable-undo`	32.10 アンドゥリストの保守
	`buffer-display-count`	28.11 バッファーとウィンドウ
	`buffer-display-table`	39.22.3 アクティブなディスプレーテーブル
	`buffer-display-time`	28.11 バッファーとウィンドウ
	`buffer-enable-undo`	32.10 アンドゥリストの保守
	`buffer-end`	30.1 ポイント
	`buffer-file-coding-system`	33.10.2 エンコーディングとI/O
	`buffer-file-format`	25.13.2 ラウンドトリップ仕様
	`buffer-file-name`	27.4 バッファーのファイル名
	`buffer-file-name`	27.4 バッファーのファイル名
	`buffer-file-number`	27.4 バッファーのファイル名
	`buffer-file-truename`	27.4 バッファーのファイル名
	`buffer-hash`	32.26 チェックサムとハッシュ
	`buffer-invisibility-spec`	39.6 不可視のテキスト
	`buffer-list`	27.8 バッファーリスト
	`buffer-list, a frame parameter`	29.4.3.5 バッファーのパラメーター
	`buffer-list-update-hook`	27.8 バッファーリスト
	`buffer-list-update-hook`	Appendix H 標準的なフック
	`buffer-live-p`	27.10 バッファーのkill
	buffer-local variables	12.11 バッファーローカル変数
	buffer-local variables in modes	23.2.1 メジャーモードの慣習
	`buffer-local-value`	12.11.2 バッファーローカルなバインディングの作成と削除
	`buffer-local-variables`	12.11.2 バッファーローカルなバインディングの作成と削除
	`buffer-modified-p`	27.5 バッファーの変更
	`buffer-modified-tick`	27.5 バッファーの変更
	`buffer-name`	27.3 バッファーの名前
	`buffer-name-history`	20.4 ミニバッファーのヒストリー
	`buffer-narrowed-p`	30.4 ナローイング
	`buffer-offer-save`	27.10 バッファーのkill
	`buffer-predicate, a frame parameter`	29.4.3.5 バッファーのパラメーター
	`buffer-quit-function`	Appendix H 標準的なフック
	`buffer-read-only`	27.7 読み取り専用のバッファー
	`buffer-save-without-query`	27.10 バッファーのkill
	`buffer-saved-size`	26.2 自動保存
	`buffer-size`	30.1 ポイント
	`buffer-stale-function`	26.3 リバート
	`buffer-string`	32.2 バッファーのコンテンツを調べる
	`buffer-substring`	32.2 バッファーのコンテンツを調べる
	`buffer-substring-filters`	32.2 バッファーのコンテンツを調べる
	`buffer-substring-no-properties`	32.2 バッファーのコンテンツを調べる
	`buffer-substring-with-bidi-context`	39.26 双方向テキストの表示
	`buffer-swap-text`	27.12 2つのバッファー間でのテキストの交換
	`buffer-undo-list`	32.9 アンドゥ
	`bufferp`	27.1 バッファーの基礎
	`bufferpos-to-filepos`	33.1 テキストの表現方法
	buffers to display on frame	29.4.3.5 バッファーのパラメーター
	buffers without undo information	27.3 バッファーの名前
	buffers, controlled in windows	28.11 バッファーとウィンドウ
	buffers, creating	27.9 バッファーの作成
	buffers, killing	27.10 バッファーのkill
	bugs	1.1 注意事項
	bugs in this manual	1.1 注意事項
	build details	E.1 Emacsのビルド
	building Emacs	E.1 Emacsのビルド
	building lists	5.4 コンスセルおよびリストの構築
	built-in function	13.1 関数とは?
	`bury-buffer`	27.8 バッファーリスト
	`butlast`	5.3 リスト要素へのアクセス
	`button (button property)`	39.19.1 ボタンのプロパティ
	button buffer commands	39.19.5 ボタンのためのバッファーコマンド
	button properties	39.19.1 ボタンのプロパティ
	button types	39.19.2 ボタンのタイプ
	`button-activate`	39.19.4 ボタンの操作
	`button-at`	39.19.4 ボタンの操作
	button-down event	21.7.6 ボタンダウンイベント
	`button-end`	39.19.4 ボタンの操作
	`button-face, customization keyword`	15.4.4 型キーワード
	`button-get`	39.19.4 ボタンの操作
	`button-has-type-p`	39.19.4 ボタンの操作
	`button-label`	39.19.4 ボタンの操作
	`button-prefix, customization keyword`	15.4.4 型キーワード
	`button-put`	39.19.4 ボタンの操作
	`button-start`	39.19.4 ボタンの操作
	`button-suffix, customization keyword`	15.4.4 型キーワード
	`button-type`	39.19.4 ボタンの操作
	`button-type-get`	39.19.4 ボタンの操作
	`button-type-put`	39.19.4 ボタンの操作
	`button-type-subtype-p`	39.19.4 ボタンの操作
	buttons in buffers	39.19 ボタン
	byte compilation	17 バイトコンパイル
	byte compiler warnings, how to avoid	D.5 コンパイラー警告を回避するためのヒント
	byte packing and unpacking	38.20 バイト配列のpackとunpack
	byte to string	33.3 テキスト表現の変換
	`byte-boolean-vars`	12.16 値を制限された変数
	`byte-boolean-vars`	E.7 Emacsプリミティブの記述
	byte-code	17 バイトコンパイル
	byte-code function	17.7 バイトコード関数オブジェクト
	byte-code object	17.7 バイトコード関数オブジェクト
	`byte-code-function-p`	13.1 関数とは?
	`byte-compile`	17.2 バイトコンパイル関数
	`byte-compile-debug`	17.2 バイトコンパイル関数
	`byte-compile-dynamic`	17.4 個別関数のダイナミックロード
	`byte-compile-dynamic-docstrings`	17.3 ドキュメント文字列とコンパイル
	`byte-compile-error-on-warn`	17.6 コンパイラーのエラー
	`byte-compile-file`	17.2 バイトコンパイル関数
	byte-compiler errors	17.6 コンパイラーのエラー
	byte-compiler warnings	17.6 コンパイラーのエラー
	byte-compiling macros	14.3 マクロとバイトコンパイル
	byte-compiling `require`	16.7 名前つき機能
	`byte-recompile-directory`	17.2 バイトコンパイル関数
	`byte-to-position`	33.1 テキストの表現方法
	`byte-to-string`	33.3 テキスト表現の変換
	bytes	4 文字列と文字
	bytesize, in serial connections	38.19 シリアルポートとの対話

C
	C programming language	E.6 C方言
	`C-c`	22.6 プレフィクスキー
	`C-g`	21.11 quit
	`C-h`	22.6 プレフィクスキー
	`C-M-x`	18.2.2 Edebugのためのインストルメント
	`C-x`	22.6 プレフィクスキー
	`C-x 4`	22.6 プレフィクスキー
	`C-x 5`	22.6 プレフィクスキー
	`C-x 6`	22.6 プレフィクスキー
	`C-x C-a C-m`	18.2.3 Edebugの実行モード
	`C-x RET`	22.6 プレフィクスキー
	`C-x v`	22.6 プレフィクスキー
	`C-x X =`	18.2.13 カバレッジテスト
	`caaaar`	5.3 リスト要素へのアクセス
	`caaadr`	5.3 リスト要素へのアクセス
	`caaar`	5.3 リスト要素へのアクセス
	`caadar`	5.3 リスト要素へのアクセス
	`caaddr`	5.3 リスト要素へのアクセス
	`caadr`	5.3 リスト要素へのアクセス
	`caar`	5.3 リスト要素へのアクセス
	`cadaar`	5.3 リスト要素へのアクセス
	`cadadr`	5.3 リスト要素へのアクセス
	`cadar`	5.3 リスト要素へのアクセス
	`caddar`	5.3 リスト要素へのアクセス
	`cadddr`	5.3 リスト要素へのアクセス
	`caddr`	5.3 リスト要素へのアクセス
	`cadr`	5.3 リスト要素へのアクセス
	calendrical computations	40.10 時間の計算
	calendrical information	40.7 時刻の変換
	call stack	18.1.9 デバッガの内部
	`call-interactively`	21.3 interactiveな呼び出し
	`call-process`	38.3 同期プロセスの作成
	`call-process`, command-line arguments from minibuffer	38.2 shell引数
	`call-process-region`	38.3 同期プロセスの作成
	`call-process-shell-command`	38.3 同期プロセスの作成
	`call-shell-region`	38.3 同期プロセスの作成
	`called-interactively-p`	21.4 interactiveな呼び出しの区別
	calling a function	13.5 関数の呼び出し
	`cancel-change-group`	32.29 グループのアトミックな変更
	`cancel-debug-on-entry`	18.1.3 関数呼び出しによるデバッガへのエンター
	`cancel-debug-on-variable-change`	18.1.4 Entering the debugger when a variable is modified
	`cancel-timer`	40.11 遅延実行のためのタイマー
	canonical character height	29.3.2 Frame Font
	canonical character width	29.3.2 Frame Font
	capitalization	4.8 Lispでの大文字小文字変換
	`capitalize`	4.8 Lispでの大文字小文字変換
	`capitalize-region`	32.18 大文字小文字の変更
	`capitalize-word`	32.18 大文字小文字の変更
	caption bar	29.3.1 Frame Layout
	`car`	5.3 リスト要素へのアクセス
	`car-safe`	5.3 リスト要素へのアクセス
	case conversion in buffers	32.18 大文字小文字の変更
	case conversion in Lisp	4.8 Lispでの大文字小文字変換
	case in replacements	34.6.1 マッチしたテキストの置換
	`case-fold-search`	34.2 検索と大文字小文字
	`case-replace`	34.2 検索と大文字小文字
	`case-table-p`	4.9 caseテーブル
	`catch`	11.6.1 明示的な非ローカル脱出: `catch`と`throw`
	categories of characters	35.8 カテゴリー
	`category (overlay property)`	39.9.2 オーバーレイのプロパティ
	`category (text property)`	32.19.4 特殊な意味をもつプロパティ
	category set	35.8 カテゴリー
	category table	35.8 カテゴリー
	category, regexp search for	34.3.1.3 正規表現内のバッククラッシュ構造
	`category-docstring`	35.8 カテゴリー
	`category-set-mnemonics`	35.8 カテゴリー
	`category-table`	35.8 カテゴリー
	`category-table-p`	35.8 カテゴリー
	`cdaaar`	5.3 リスト要素へのアクセス
	`cdaadr`	5.3 リスト要素へのアクセス
	`cdaar`	5.3 リスト要素へのアクセス
	`cdadar`	5.3 リスト要素へのアクセス
	`cdaddr`	5.3 リスト要素へのアクセス
	`cdadr`	5.3 リスト要素へのアクセス
	`cdar`	5.3 リスト要素へのアクセス
	`cddaar`	5.3 リスト要素へのアクセス
	`cddadr`	5.3 リスト要素へのアクセス
	`cddar`	5.3 リスト要素へのアクセス
	`cdddar`	5.3 リスト要素へのアクセス
	`cddddr`	5.3 リスト要素へのアクセス
	`cdddr`	5.3 リスト要素へのアクセス
	`cddr`	5.3 リスト要素へのアクセス
	`cdr`	5.3 リスト要素へのアクセス
	`cdr-safe`	5.3 リスト要素へのアクセス
	`ceiling`	3.5 数値の変換
	centering point	28.23 テキスト的なスクロール
	change hooks	32.30 フックの変更
	change hooks for a character	32.19.4 特殊な意味をもつプロパティ
	change `load-path` at configure time	E.1 Emacsのビルド
	`change-major-mode-after-body-hook`	23.2.6 モードフック
	`change-major-mode-hook`	12.11.2 バッファーローカルなバインディングの作成と削除
	changing key bindings	22.12 キーバインディングの変更
	changing text properties	32.19.2 テキストプロパティの変更
	changing to another buffer	27.2 カレントバッファー
	changing window size	28.4 ウィンドウのリサイズ
	`char-after`	32.1 ポイント周辺のテキストを調べる
	`char-before`	32.1 ポイント周辺のテキストを調べる
	`char-category-set`	35.8 カテゴリー
	`char-charset`	33.7 文字セット
	`char-code-property-description`	33.6 文字のプロパティ
	`char-displayable-p`	39.12.11 フォントセット
	`char-equal`	4.5 文字および文字列の比較
	`char-from-name`	33.5 文字コード
	`char-or-string-p`	4.2 文字列のための述語
	`char-property-alias-alist`	32.19.1 テキストプロパティを調べる
	`char-script-table`	33.6 文字のプロパティ
	`char-syntax`	35.3 構文テーブルの関数
	char-table length	6.1 シーケンス
	`char-table-extra-slot`	6.6 文字テーブル
	`char-table-p`	6.6 文字テーブル
	`char-table-parent`	6.6 文字テーブル
	`char-table-range`	6.6 文字テーブル
	`char-table-subtype`	6.6 文字テーブル
	char-tables	6.6 文字テーブル
	`char-to-string`	4.6 文字および文字列の変換
	`char-width`	39.10 表示されるテキストのサイズ
	`char-width-table`	33.6 文字のプロパティ
	character alternative (in regexp)	34.3.1.1 正規表現内の特殊文字
	character arrays	4 文字列と文字
	character case	4.8 Lispでの大文字小文字変換
	character categories	35.8 カテゴリー
	character classes in regexp	34.3.1.2 文字クラス
	character code conversion	33.10.1 コーディングシステムの基本概念
	character codepoint	33.1 テキストの表現方法
	character codes	33.5 文字コード
	character insertion	32.5 ユーザーレベルの挿入コマンド
	character printing	24.5 ヘルプメッセージの文字記述
	character properties	33.6 文字のプロパティ
	character set, searching	33.8 文字セットのスキャン
	character sets	33.7 文字セット
	character to string	4.6 文字および文字列の変換
	character translation tables	33.9 文字の変換
	character width on display	39.10 表示されるテキストのサイズ
	`characterp`	33.5 文字コード
	characters	4 文字列と文字
	characters for interactive codes	21.2.2 `interactive`にたいするコード文字
	characters, multi-byte	33 非ASCII文字
	characters, representation in buffers and strings	33.1 テキストの表現方法
	charset	33.7 文字セット
	charset, coding systems to encode	33.10.3 Lispでのコーディングシステム
	`charset`, text property	33.10.7 明示的なエンコードとデコード
	`charset-after`	33.8 文字セットのスキャン
	`charset-list`	33.7 文字セット
	`charset-plist`	33.7 文字セット
	`charset-priority-list`	33.7 文字セット
	`charsetp`	33.7 文字セット
	charsets supported by a coding system	33.10.3 Lispでのコーディングシステム
	`check-coding-system`	33.10.3 Lispでのコーディングシステム
	`check-coding-systems-region`	33.10.3 Lispでのコーディングシステム
	`checkdoc`	Appendix D ヒントと規約
	`checkdoc-current-buffer`	Appendix D ヒントと規約
	`checkdoc-file`	Appendix D ヒントと規約
	`checkdoc-minor-mode`	D.6 ドキュメント文字列のヒント
	`checkdoc-package-keywords`	D.8 Emacsライブラリーのヘッダーの慣習
	`checkdoc-package-keywords-flag`	D.8 Emacsライブラリーのヘッダーの慣習
	child frames	29.14 Child Frames
	child process	38 プロセス
	child window	28.2 ウィンドウとフレーム
	choice, customization types	15.4.3 リストへのスプライス
	cipher, AEAD	32.27 GnuTLS Cryptography
	cipher, symmetric	32.27 GnuTLS Cryptography
	circular list	5.1 リストとコンスセル
	circular structure, read syntax	2.5 循環オブジェクトの読み取り構文
	`cl`	1.2 Lispの歴史
	CL note—allocate more storage	E.3 ガーベージコレクション
	CL note—case of letters	2.3.4 シンボル型
	CL note—default optional arg	13.2.3 引数リストのその他機能
	CL note—integers vrs `eq`	3.4 数値の比較
	CL note—interning existing symbol	9.3 シンボルの作成とintern
	CL note—lack `union`, `intersection`	5.7 集合としてのリストの使用
	CL note—no continuable errors	11.6.3.1 エラーをシグナルする方法
	CL note—no `setf` functions	12.17.2 新たな`setf`フォーム
	CL note—only `throw` in Emacs	11.6.1 明示的な非ローカル脱出: `catch`と`throw`
	CL note—`rplaca` vs `setcar`	5.6 既存のリスト構造の変更
	CL note—special forms compared	10.2.7 スペシャルフォーム
	CL note—symbol in obarrays	9.3 シンボルの作成とintern
	`cl-call-next-method`	13.8 Generic Functions
	`cl-defgeneric`	13.8 Generic Functions
	`cl-defmethod`	13.8 Generic Functions
	`cl-next-method-p`	13.8 Generic Functions
	`cl-old-struct-compat-mode`	7.2 Backward Compatibility
	classification of file types	25.6.2 ファイル種別の区別
	classifying events	21.7.12 イベントの分類
	cleanup forms	11.6.4 非ローカル脱出のクリーンアップ
	`clear-abbrev-table`	36.1 abbrevテーブル
	`clear-image-cache`	39.17.11 イメージキャッシュ
	`clear-string`	4.4 文字列の変更
	`clear-this-command-keys`	21.5 コマンドループからの情報
	`clear-visited-file-modtime`	27.6 バッファーの変更 Time
	click event	21.7.4 クリックイベント
	clickable buttons in buffers	39.19 ボタン
	clickable text	32.19.8 クリック可能なテキストの定義
	clipboard	29.20 ウィンドウシステムによる選択
	clipboard support (for MS-Windows)	29.20 ウィンドウシステムによる選択
	`clone-indirect-buffer`	27.11 インダイレクトバッファー
	`clone-of, a window parameter`	28.29 ウィンドウのパラメーター
	CLOS	13.8 Generic Functions
	closure	13.10 クロージャー
	closures, example of using	12.10.3 レキシカルバインディング
	`clrhash`	8.2 ハッシュテーブルへのアクセス
	coded character set	33.7 文字セット
	codepoint, largest value	33.5 文字コード
	codes, interactive, description of	21.2.2 `interactive`にたいするコード文字
	codespace	33.1 テキストの表現方法
	coding conventions in Emacs Lisp	D.1 Emacs Lispコーディングの慣習
	coding standards	Appendix D ヒントと規約
	coding system	33.10 コーディングシステム
	coding system for operation	33.10.6 単一の操作にたいするコーディングシステムの指定
	coding system, automatically determined	33.10.5 デフォルトのコーディングシステム
	coding system, validity check	33.10.3 Lispでのコーディングシステム
	coding systems for encoding a string	33.10.3 Lispでのコーディングシステム
	coding systems for encoding region	33.10.3 Lispでのコーディングシステム
	coding systems, priority	33.10.6 単一の操作にたいするコーディングシステムの指定
	`coding-system-aliases`	33.10.1 コーディングシステムの基本概念
	`coding-system-change-eol-conversion`	33.10.3 Lispでのコーディングシステム
	`coding-system-change-text-conversion`	33.10.3 Lispでのコーディングシステム
	`coding-system-charset-list`	33.10.3 Lispでのコーディングシステム
	`coding-system-eol-type`	33.10.3 Lispでのコーディングシステム
	`coding-system-for-read`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`coding-system-for-write`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`coding-system-get`	33.10.1 コーディングシステムの基本概念
	`coding-system-list`	33.10.3 Lispでのコーディングシステム
	`coding-system-p`	33.10.3 Lispでのコーディングシステム
	`coding-system-priority-list`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`coding-system-require-warning`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`collapse-delayed-warnings`	39.5.4 遅延された警告
	color names	29.22 カラー名
	`color-defined-p`	29.22 カラー名
	`color-gray-p`	29.22 カラー名
	`color-supported-p`	29.22 カラー名
	`color-values`	29.22 カラー名
	colors on text terminals	29.23 テキスト端末のカラー
	column width	29.3.2 Frame Font
	columns	32.16 列を数える
	`COM1`	38.19 シリアルポートとの対話
	`combine-after-change-calls`	32.30 フックの変更
	`combine-and-quote-strings`	38.2 shell引数
	combining conditions	11.3 条件の組み合わせ
	command	13.1 関数とは?
	command descriptions	1.3.7.1 関数の説明例
	command history	21.15 コマンドのヒストリー
	command in keymap	22.10 キーの照合
	command loop	21 コマンドループ
	command loop variables	21.5 コマンドループからの情報
	command loop, recursive	21.13 再帰編集
	`command-debug-status`	18.1.9 デバッガの内部
	`command-error-function`	11.6.3.2 Emacsがエラーを処理する方法
	`command-execute`	21.3 interactiveな呼び出し
	`command-history`	21.15 コマンドのヒストリー
	`command-line`	40.1.4 コマンドライン引数
	command-line arguments	40.1.4 コマンドライン引数
	command-line options	40.1.4 コマンドライン引数
	`command-line-args`	40.1.4 コマンドライン引数
	`command-line-args-left`	40.1.4 コマンドライン引数
	`command-line-functions`	40.1.4 コマンドライン引数
	`command-line-processed`	40.1.4 コマンドライン引数
	`command-remapping`	22.13 コマンドのリマップ
	`command-switch-alist`	40.1.4 コマンドライン引数
	`commandp`	21.3 interactiveな呼び出し
	`commandp` example	20.6.4 高レベルの補完関数
	commands, defining	21.2 コマンドの定義
	comment style	35.2.2 構文フラグ
	comment syntax	35.2.1 構文クラスのテーブル
	`comment-auto-fill-only-comments`	32.14 オートfill
	`comment-end-can-be-escaped`	35.6.5 パースを制御するためのパラメーター
	commentary, in a Lisp library	D.8 Emacsライブラリーのヘッダーの慣習
	comments	2.2 コメント
	comments, Lisp convention for	D.7 コメント記述のヒント
	Common Lisp	1.2 Lispの歴史
	`compare-buffer-substrings`	32.3 テキストの比較
	`compare-strings`	4.5 文字および文字列の比較
	`compare-window-configurations`	28.28 ウィンドウの構成
	comparing buffer text	32.3 テキストの比較
	comparing file modification time	27.6 バッファーの変更 Time
	comparing numbers	3.4 数値の比較
	comparing time values	40.10 時間の計算
	compilation (Emacs Lisp)	17 バイトコンパイル
	compilation functions	17.2 バイトコンパイル関数
	`compile-defun`	17.2 バイトコンパイル関数
	compile-time constant	17.5 コンパイル中の評価
	compiled function	17.7 バイトコード関数オブジェクト
	compiler errors	17.6 コンパイラーのエラー
	complete key	22.2 キーマップの基礎
	`completing-read`	20.6.2 補完とミニバッファー
	`completing-read-function`	20.6.2 補完とミニバッファー
	completion	20.6 補完
	completion styles	20.6.6 補完変数
	completion table	20.6.1 基本的な補完関数
	completion table, modifying	20.6.1 基本的な補完関数
	completion tables, combining	20.6.1 基本的な補完関数
	completion, file name	25.9.6 ファイル名の補完
	`completion-at-point`	20.6.8 通常バッファーでの補完
	`completion-at-point-functions`	20.6.8 通常バッファーでの補完
	`completion-auto-help`	20.6.3 補完を行うミニバッファーコマンド
	`completion-boundaries`	20.6.1 基本的な補完関数
	`completion-category-overrides`	20.6.6 補完変数
	`completion-extra-properties`	20.6.6 補完変数
	`completion-ignore-case`	20.6.1 基本的な補完関数
	`completion-ignored-extensions`	25.9.6 ファイル名の補完
	`completion-in-region`	20.6.8 通常バッファーでの補完
	`completion-regexp-list`	20.6.1 基本的な補完関数
	`completion-styles`	20.6.6 補完変数
	`completion-styles-alist`	20.6.6 補完変数
	`completion-table-case-fold`	20.6.1 基本的な補完関数
	`completion-table-dynamic`	20.6.7 プログラムされた補完
	`completion-table-in-turn`	20.6.1 基本的な補完関数
	`completion-table-merge`	20.6.1 基本的な補完関数
	`completion-table-subvert`	20.6.1 基本的な補完関数
	`completion-table-with-cache`	20.6.7 プログラムされた補完
	`completion-table-with-predicate`	20.6.1 基本的な補完関数
	`completion-table-with-quoting`	20.6.1 基本的な補完関数
	`completion-table-with-terminator`	20.6.1 基本的な補完関数
	complex arguments	20 ミニバッファー
	complex command	21.15 コマンドのヒストリー
	composite types (customization)	15.4.2 複合型
	`composition (text property)`	32.19.4 特殊な意味をもつプロパティ
	`composition` property, and point display	21.6 コマンド後のポイントの調整
	`compute-motion`	30.2.5 スクリーン行単位の移動
	`concat`	4.3 文字列の作成
	concatenating bidirectional strings	39.26 双方向テキストの表示
	concatenating lists	5.6.3 リストを再配置する関数
	concatenating strings	4.3 文字列の作成
	concurrency	37 Threads
	`cond`	11.2 条件
	condition name	11.6.3.4 エラーシンボルとエラー条件
	`condition-case`	11.6.3.3 エラーを処理するコードの記述
	`condition-case-unless-debug`	11.6.3.3 エラーを処理するコードの記述
	`condition-mutex`	37.3 Condition Variables
	`condition-name`	37.3 Condition Variables
	`condition-notify`	37.3 Condition Variables
	`condition-variable-p`	37.3 Condition Variables
	`condition-wait`	37.3 Condition Variables
	conditional evaluation	11.2 条件
	conditional selection of windows	28.10 ウィンドウのサイクル順
	`confirm-kill-processes`	38.11 exit前の問い合わせ
	connection local variables	12.14 Connection Local Variables
	`connection-local-criteria-alist`	12.14 Connection Local Variables
	`connection-local-profile-alist`	12.14 Connection Local Variables
	`connection-local-set-profile-variables`	12.14 Connection Local Variables
	`connection-local-set-profiles`	12.14 Connection Local Variables
	`cons`	5.4 コンスセルおよびリストの構築
	cons cells	5.4 コンスセルおよびリストの構築
	`cons-cells-consed`	E.5 メモリー使用量
	consing	5.4 コンスセルおよびリストの構築
	`consp`	5.2 リストのための述語
	constant variables	12.2 変更不可な変数
	constant variables	12.5 グローバル変数の定義
	`constrain-to-field`	32.19.9 フィールドの定義と使用
	content directory, package	41.1 パッケージ化の基礎
	continuation lines	39.3 切り詰め
	`continue-process`	38.8 プロセスへのシグナルの送信
	control character key constants	22.12 キーバインディングの変更
	control character printing	24.5 ヘルプメッセージの文字記述
	control characters	2.3.3.3 コントロール文字構文
	control characters in display	39.22.1 通常の表示の慣習
	control characters, reading	21.8.5 クォートされた文字の入力
	control structures	11 制御構造
	`Control-X-prefix`	22.6 プレフィクスキー
	controller part, model/view/controller	39.20.2 抽象ディスプレーの例
	controlling terminal	40.2.2 Emacsのサスペンド
	`controlling-tty-p`	40.2.2 Emacsのサスペンド
	conventions for writing major modes	23.2.1 メジャーモードの慣習
	conventions for writing minor modes	23.3.1 マイナーモード記述の規約
	conversion of strings	4.6 文字および文字列の変換
	convert buffer position to file byte	33.1 テキストの表現方法
	convert file byte to buffer position	33.1 テキストの表現方法
	convert sequence to another type	6.1 シーケンス
	`convert-standard-filename`	25.9.7 標準的なファイル名
	converting file names from/to MS-Windows syntax	25.9 ファイルの名前
	converting numbers	3.5 数値の変換
	coordinate, relative to frame	28.26 座標とウィンドウ
	`coordinates-in-window-p`	28.26 座標とウィンドウ
	`copy-abbrev-table`	36.1 abbrevテーブル
	`copy-alist`	5.8 連想リスト
	`copy-category-table`	35.8 カテゴリー
	`copy-directory`	25.11 ディレクトリーの作成・コピー・削除
	`copy-file`	25.7 ファイルの名前と属性の変更
	`copy-hash-table`	8.4 ハッシュテーブルのためのその他関数
	`copy-keymap`	22.4 キーマップの作成
	`copy-marker`	31.3 マーカーを作成する関数
	`copy-overlay`	39.9.1 オーバーレイの管理
	`copy-region-as-kill`	32.8.2 killリングのための関数
	`copy-sequence`	6.1 シーケンス
	`copy-syntax-table`	35.3 構文テーブルの関数
	`copy-tree`	5.4 コンスセルおよびリストの構築
	copying alists	5.8 連想リスト
	copying bidirectional text, preserve visual order	39.26 双方向テキストの表示
	copying files	25.7 ファイルの名前と属性の変更
	copying lists	5.4 コンスセルおよびリストの構築
	copying sequences	6.1 シーケンス
	copying strings	4.3 文字列の作成
	copying vectors	6.5 ベクターのための関数
	`copysign`	3.2 浮動小数点数の基礎
	`cos`	3.9 標準的な数学関数
	`count-lines`	30.2.4 テキスト行単位の移動
	`count-loop`	1.3.7.1 関数の説明例
	`count-screen-lines`	30.2.5 スクリーン行単位の移動
	`count-words`	30.2.4 テキスト行単位の移動
	counting columns	32.16 列を数える
	coverage testing	18.4 カバレッジテスト
	coverage testing (Edebug)	18.2.13 カバレッジテスト
	create subprocess	38.1 サブプロセスを作成する関数
	`create-file-buffer`	25.1.2 visitのためのサブルーチン
	`create-fontset-from-fontset-spec`	39.12.11 フォントセット
	`create-image`	39.17.8 イメージの定義
	`create-lockfiles`	25.5 ファイルのロック
	creating buffers	27.9 バッファーの作成
	creating hash tables	8.1 ハッシュテーブルの作成
	creating keymaps	22.4 キーマップの作成
	creating markers	31.3 マーカーを作成する関数
	creating strings	4.3 文字列の作成
	creating, copying and deleting directories	25.11 ディレクトリーの作成・コピー・削除
	cryptographic hash	32.26 チェックサムとハッシュ
	cryptographic hash	32.27 GnuTLS Cryptography
	`ctl-arrow`	39.22.1 通常の表示の慣習
	`ctl-x-4-map`	22.6 プレフィクスキー
	`ctl-x-5-map`	22.6 プレフィクスキー
	`ctl-x-map`	22.6 プレフィクスキー
	`ctl-x-r-map`	Appendix G 標準的なキーマップ
	curly quotes	24.3 ドキュメント内でのキーバインディングの置き換え
	curly quotes	24.4 Text Quoting Style
	curly quotes	D.6 ドキュメント文字列のヒント
	curly quotes, in formatted messages	4.7 文字列のフォーマット
	current binding	12.3 ローカル変数
	current buffer	27.2 カレントバッファー
	current buffer mark	31.7 マーク
	current buffer point and mark (Edebug)	18.2.14.2 Edebugの表示の更新
	current buffer position	30.1 ポイント
	current command	21.5 コマンドループからの情報
	current stack frame	18.1.6 デバッガの使用
	`current-active-maps`	22.7 アクティブなキーマップ
	`current-bidi-paragraph-direction`	39.26 双方向テキストの表示
	`current-buffer`	27.2 カレントバッファー
	`current-case-table`	4.9 caseテーブル
	`current-column`	32.16 列を数える
	`current-fill-column`	32.12 fillのマージン
	`current-frame-configuration`	29.13 フレーム構成
	`current-global-map`	22.9 アクティブなキーマップの制御
	`current-idle-time`	40.12 アイドルタイマー
	`current-indentation`	32.17.1 インデント用のプリミティブ
	`current-input-method`	33.11 入力メソッド
	`current-input-mode`	40.13.1 入力のモード
	`current-justification`	32.11 fill
	`current-kill`	32.8.5 低レベルのkillリング
	`current-left-margin`	32.12 fillのマージン
	`current-local-map`	22.9 アクティブなキーマップの制御
	`current-message`	39.4.1 エコーエリアへのメッセージの表示
	`current-minor-mode-maps`	22.9 アクティブなキーマップの制御
	`current-prefix-arg`	21.12 プレフィクスコマンド引数
	`current-thread`	37.1 Basic Thread Functions
	`current-time`	40.5 時刻
	`current-time-string`	40.5 時刻
	`current-time-zone`	40.6 Time Zone Rules
	`current-window-configuration`	28.28 ウィンドウの構成
	`current-word`	32.2 バッファーのコンテンツを調べる
	currying	13.5 関数の呼び出し
	cursor	28.21 ウィンドウとポイント
	`cursor (text property)`	32.19.4 特殊な意味をもつプロパティ
	cursor position for `display` properties and overlays	32.19.4 特殊な意味をもつプロパティ
	cursor, and frame parameters	29.4.3.9 カーソルのパラメーター
	cursor, fringe	39.13.3 フリンジのカーソルFringe Cursors
	`cursor-color, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`cursor-in-echo-area`	39.4.4 エコーエリアのカスタマイズ
	`cursor-in-non-selected-windows`	29.4.3.9 カーソルのパラメーター
	`cursor-intangible (text property)`	32.19.4 特殊な意味をもつプロパティ
	`cursor-intangible-mode`	32.19.4 特殊な意味をもつプロパティ
	`cursor-sensor-functions (text property)`	32.19.4 特殊な意味をもつプロパティ
	`cursor-sensor-mode`	32.19.4 特殊な意味をもつプロパティ
	`cursor-type`	29.4.3.9 カーソルのパラメーター
	`cursor-type`	29.4.3.9 カーソルのパラメーター
	`cursor-type, a frame parameter`	29.4.3.9 カーソルのパラメーター
	curved quotes	24.3 ドキュメント内でのキーバインディングの置き換え
	curved quotes	24.4 Text Quoting Style
	curved quotes	D.6 ドキュメント文字列のヒント
	curved quotes, in formatted messages	4.7 文字列のフォーマット
	`cust-print`	18.2.11 Edebugでのプリント
	custom themes	15.6 カスタムテーマ
	`custom-add-frequent-value`	15.3 カスタマイズ変数の定義
	`custom-group` property	15.2 カスタマイズグループの定義
	`custom-initialize-delay`	E.1 Emacsのビルド
	`custom-known-themes`	15.6 カスタムテーマ
	`custom-reevaluate-setting`	15.3 カスタマイズ変数の定義
	`custom-set-faces`	15.5 カスタマイズの適用
	`custom-set-variables`	15.5 カスタマイズの適用
	`custom-theme-p`	15.6 カスタムテーマ
	`custom-theme-set-faces`	15.6 カスタムテーマ
	`custom-theme-set-variables`	15.6 カスタムテーマ
	`custom-unlispify-remove-prefixes`	15.2 カスタマイズグループの定義
	`custom-variable-p`	15.3 カスタマイズ変数の定義
	customizable variables, how to define	15.3 カスタマイズ変数の定義
	customization groups, defining	15.2 カスタマイズグループの定義
	customization item	15 カスタマイズ設定
	customization keywords	15.1 一般的なキーワードアイテム
	customization types	15.4 カスタマイズ型
	customization types, define new	15.4.5 新たな型の定義
	`customize-package-emacs-version-alist`	15.1 一般的なキーワードアイテム
	cyclic ordering of windows	28.10 ウィンドウのサイクル順
	`cygwin-convert-file-name-from-windows`	25.9 ファイルの名前
	`cygwin-convert-file-name-to-windows`	25.9 ファイルの名前

D
	data type	2 Lispのデータ型
	`data-directory`	24.6 ヘルプ関数
	datagrams	38.16 データグラム
	`date-leap-year-p`	40.10 時間の計算
	`date-to-time`	40.8 時刻のパースとフォーマット
	`deactivate-mark`	31.7 マーク
	`deactivate-mark`	31.7 マーク
	`deactivate-mark-hook`	31.7 マーク
	`debug`	18.1.8 デバッガの呼び出し
	`debug-ignored-errors`	18.1.1 エラーによるデバッガへのエンター
	`debug-on-entry`	18.1.3 関数呼び出しによるデバッガへのエンター
	`debug-on-error`	18.1.1 エラーによるデバッガへのエンター
	`debug-on-error` use	11.6.3.2 Emacsがエラーを処理する方法
	`debug-on-event`	18.1.1 エラーによるデバッガへのエンター
	`debug-on-message`	18.1.1 エラーによるデバッガへのエンター
	`debug-on-next-call`	18.1.9 デバッガの内部
	`debug-on-quit`	18.1.2 無限ループのデバッグ
	`debug-on-signal`	18.1.1 エラーによるデバッガへのエンター
	`debug-on-variable-change`	18.1.4 Entering the debugger when a variable is modified
	`debugger`	18.1.9 デバッガの内部
	debugger command list	18.1.7 デバッガのコマンド
	debugger for Emacs Lisp	18.1 Lispデバッガ
	debugger, explicit entry	18.1.5 明示的なデバッガへのエントリー
	`debugger-bury-or-kill`	18.1.6 デバッガの使用
	`debugger-stack-frame-as-list`	18.1.9 デバッガの内部
	debugging changes to variables	18.1.4 Entering the debugger when a variable is modified
	debugging errors	18.1.1 エラーによるデバッガへのエンター
	debugging invalid Lisp syntax	18.3 無効なLisp構文のデバッグ
	debugging lisp programs	18 Lispプログラムのデバッグ
	debugging specific functions	18.1.3 関数呼び出しによるデバッガへのエンター
	`declare`	13.14 `declare`フォーム
	`declare`	13.14 `declare`フォーム
	`declare-function`	13.15 コンパイラーへの定義済み関数の指示
	`declare-function`	13.15 コンパイラーへの定義済み関数の指示
	declaring functions	13.15 コンパイラーへの定義済み関数の指示
	decode process output	38.9.3 プロセス出力のデコード
	`decode-char`	33.7 文字セット
	`decode-coding-inserted-region`	33.10.7 明示的なエンコードとデコード
	`decode-coding-region`	33.10.7 明示的なエンコードとデコード
	`decode-coding-string`	33.10.7 明示的なエンコードとデコード
	`decode-time`	40.7 時刻の変換
	decoding file formats	25.13 ファイルのフォーマット変換
	decoding in coding systems	33.10.7 明示的なエンコードとデコード
	decrement field of register	2.3.6 コンスセルとリスト型
	dedicated window	28.17 専用のウィンドウ
	`def-edebug-spec`	18.2.15.1 マクロ呼び出しのインストルメント
	`defadvice`	13.11.4 古いdefadviceを使用するコードの改良
	`defalias`	13.4 関数の定義
	defalias-fset-function property	13.4 関数の定義
	default argument string	21.2.2 `interactive`にたいするコード文字
	default character height	29.3.2 Frame Font
	default character size	29.3.2 Frame Font
	default character width	29.3.2 Frame Font
	default coding system	33.10.5 デフォルトのコーディングシステム
	default coding system, functions to determine	33.10.5 デフォルトのコーディングシステム
	default filter function of a process	38.9.2 プロセスのフィルター関数
	default font	29.3.2 Frame Font
	default height of character	29.3.2 Frame Font
	default init file	40.1.2 initファイル
	default key binding	22.3 キーマップのフォーマット
	default sentinel function of a process	38.10 センチネル: プロセス状態の変更の検知
	default value	12.11.3 バッファーローカル変数のデフォルト値
	default value of char-table	6.6 文字テーブル
	default width of character	29.3.2 Frame Font
	`default-boundp`	12.11.3 バッファーローカル変数のデフォルト値
	`default-directory`	25.9.4 ファイル名を展開する関数
	`default-file-modes`	25.7 ファイルの名前と属性の変更
	`default-font-height`	39.12.12 低レベルのフォント表現
	`default-font-width`	39.12.12 低レベルのフォント表現
	`default-frame-alist`	29.4.2 フレームの初期パラメーター
	`default-input-method`	33.11 入力メソッド
	`default-justification`	32.11 fill
	`default-minibuffer-frame`	29.9 ミニバッファーとフレーム
	`default-process-coding-system`	33.10.5 デフォルトのコーディングシステム
	`default-text-properties`	32.19.1 テキストプロパティを調べる
	`default-toplevel-value`	12.11.3 バッファーローカル変数のデフォルト値
	`default-value`	12.11.3 バッファーローカル変数のデフォルト値
	`default.el`	40.1.1 要約: スタートアップ時のアクション順序
	`defconst`	12.5 グローバル変数の定義
	`defcustom`	15.3 カスタマイズ変数の定義
	`defface`	39.12.2 フェイスの定義
	`defgroup`	15.2 カスタマイズグループの定義
	`defimage`	39.17.8 イメージの定義
	define customization group	15.2 カスタマイズグループの定義
	define customization options	15.3 カスタマイズ変数の定義
	define hash comparisons	8.3 ハッシュの比較の定義
	define image	39.17.8 イメージの定義
	define new customization types	15.4.5 新たな型の定義
	`define-abbrev`	36.2 abbrevの定義
	`define-abbrev-table`	36.1 abbrevテーブル
	`define-advice`	13.11.2 名前つき関数にたいするアドバイス
	`define-alternatives`	21.2.4 コマンド候補からの選択
	`define-button-type`	39.19.2 ボタンのタイプ
	`define-category`	35.8 カテゴリー
	`define-derived-mode`	23.2.4 派生モードの定義
	`define-error`	11.6.3.4 エラーシンボルとエラー条件
	`define-error`	11.6.3.4 エラーシンボルとエラー条件
	`define-fringe-bitmap`	39.13.5 フリンジビットマップのカスタマイズ
	`define-generic-mode`	23.2.8 ジェネリックモード
	`define-globalized-minor-mode`	23.3.3 マイナーモードの定義
	`define-hash-table-test`	8.3 ハッシュの比較の定義
	`define-inline`	13.4 関数の定義
	`define-key`	22.12 キーバインディングの変更
	`define-key-after`	22.17.7 メニューの変更
	`define-minor-mode`	23.3.3 マイナーモードの定義
	`define-obsolete-face-alias`	39.12.6 フェイスを処理するための関数
	`define-obsolete-function-alias`	13.12 関数を陳腐と宣言する
	`define-obsolete-variable-alias`	12.15 変数のエイリアス
	`define-package`	41.3 複数ファイルのパッケージ
	`define-prefix-command`	22.6 プレフィクスキー
	`defined-colors`	29.22 カラー名
	defining a function	13.4 関数の定義
	defining abbrevs	36.2 abbrevの定義
	defining commands	21.2 コマンドの定義
	defining customization variables in C	E.7 Emacsプリミティブの記述
	defining faces	39.12.2 フェイスの定義
	defining Lisp variables in C	E.7 Emacsプリミティブの記述
	defining macros	14.4 マクロの定義
	defining menus	22.17.1 メニューの定義
	defining tokens, SMIE	23.7.1.4 トークンの定義
	`defining-kbd-macro`	21.16 キーボードマクロ
	definitions of symbols	9.2 シンボルの定義
	`defmacro`	14.4 マクロの定義
	`defsubr`, Lisp symbol for a primitive	E.7 Emacsプリミティブの記述
	`defsubst`	13.13 インライン関数Inline Functions
	`deftheme`	15.6 カスタムテーマ
	`defun`	13.4 関数の定義
	`DEFUN`, C macro to define Lisp primitives	E.7 Emacsプリミティブの記述
	`defun-prompt-regexp`	30.2.6 バランスのとれたカッコを越えた移動
	`defvar`	12.5 グローバル変数の定義
	`defvar-local`	12.11.2 バッファーローカルなバインディングの作成と削除
	`defvaralias`	12.15 変数のエイリアス
	`DEFVAR_INT`, `DEFVAR_LISP`, `DEFVAR_BOOL`	E.7 Emacsプリミティブの記述
	`delay-mode-hooks`	23.2.6 モードフック
	delayed warnings	39.5.4 遅延された警告
	`delayed-warnings-hook`	39.5.4 遅延された警告
	`delayed-warnings-hook`	Appendix H 標準的なフック
	`delayed-warnings-list`	39.5.4 遅延された警告
	`delete`	5.7 集合としてのリストの使用
	`delete-and-extract-region`	32.6 テキストの削除
	`delete-auto-save-file-if-necessary`	26.2 自動保存
	`delete-auto-save-files`	26.2 自動保存
	`delete-backward-char`	32.6 テキストの削除
	`delete-before, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`delete-blank-lines`	32.7 ユーザーレベルの削除コマンド
	`delete-by-moving-to-trash`	25.7 ファイルの名前と属性の変更
	`delete-by-moving-to-trash`	25.11 ディレクトリーの作成・コピー・削除
	`delete-char`	32.6 テキストの削除
	`delete-directory`	25.11 ディレクトリーの作成・コピー・削除
	`delete-dups`	5.7 集合としてのリストの使用
	`delete-exited-processes`	38.5 プロセスの削除
	`delete-field`	32.19.9 フィールドの定義と使用
	`delete-file`	25.7 ファイルの名前と属性の変更
	`delete-frame`	29.7 フレームの削除
	`delete-frame` event	21.7.10 その他のシステムイベント
	`delete-frame-functions`	29.7 フレームの削除
	`delete-horizontal-space`	32.7 ユーザーレベルの削除コマンド
	`delete-indentation`	32.7 ユーザーレベルの削除コマンド
	`delete-minibuffer-contents`	20.12 ミニバッファーのコンテンツ
	`delete-old-versions`	26.1.3 番号つきバックアップファイルの作成と削除
	`delete-other-frames`	29.7 フレームの削除
	`delete-other-windows`	28.7 ウィンドウの削除
	`delete-other-windows, a window parameter`	28.29 ウィンドウのパラメーター
	`delete-overlay`	39.9.1 オーバーレイの管理
	`delete-process`	38.5 プロセスの削除
	`delete-region`	32.6 テキストの削除
	`delete-selection`, symbol property	31.7 マーク
	`delete-selection-helper`	31.7 マーク
	`delete-selection-pre-hook`	31.7 マーク
	`delete-terminal`	29.2 複数の端末
	`delete-terminal-functions`	29.2 複数の端末
	`delete-to-left-margin`	32.12 fillのマージン
	`delete-trailing-whitespace`	32.7 ユーザーレベルの削除コマンド
	`delete-window`	28.7 ウィンドウの削除
	`delete-window, a window parameter`	28.29 ウィンドウのパラメーター
	`delete-windows-on`	28.7 ウィンドウの削除
	deleting files	25.7 ファイルの名前と属性の変更
	deleting frames	29.7 フレームの削除
	deleting list elements	5.7 集合としてのリストの使用
	deleting previous char	32.6 テキストの削除
	deleting processes	38.5 プロセスの削除
	deleting text vs killing	32.6 テキストの削除
	deleting whitespace	32.7 ユーザーレベルの削除コマンド
	deleting windows	28.7 ウィンドウの削除
	`delq`	5.7 集合としてのリストの使用
	dependencies	41.1 パッケージ化の基礎
	derived mode	23.2.4 派生モードの定義
	`derived-mode-p`	23.2.4 派生モードの定義
	describe characters and events	24.5 ヘルプメッセージの文字記述
	`describe-bindings`	22.16 キーマップのスキャン
	`describe-buffer-case-table`	4.9 caseテーブル
	`describe-categories`	35.8 カテゴリー
	`describe-current-display-table`	39.22.2 ディスプレーテーブル
	`describe-display-table`	39.22.2 ディスプレーテーブル
	`describe-mode`	23.2.3 メジャーモードでのヘルプ入手
	`describe-prefix-bindings`	24.6 ヘルプ関数
	`describe-syntax`	35.3 構文テーブルの関数
	description for interactive codes	21.2.2 `interactive`にたいするコード文字
	description format	1.3.7 説明のフォーマット
	deserializing	38.20 バイト配列のpackとunpack
	desktop notifications	40.19 デスクトップ通知
	desktop save mode	23.8 Desktop Saveモード
	`desktop-buffer-mode-handlers`	23.8 Desktop Saveモード
	`desktop-save-buffer`	23.8 Desktop Saveモード
	`destroy-fringe-bitmap`	39.13.5 フリンジビットマップのカスタマイズ
	destructive list operations	5.6 既存のリスト構造の変更
	`detect-coding-region`	33.10.3 Lispでのコーディングシステム
	`detect-coding-string`	33.10.3 Lispでのコーディングシステム
	deterministic build	E.1 Emacsのビルド
	diagrams, boxed, for lists	2.3.6.1 ボックスダイアグラムとしてのリストの描写
	dialog boxes	29.18 ダイアログボックス
	`digit-argument`	21.12 プレフィクスコマンド引数
	`ding`	39.23 ビープ
	`dir-locals-class-alist`	12.13 ディレクトリーローカル変数
	`dir-locals-directory-cache`	12.13 ディレクトリーローカル変数
	`dir-locals-file`	12.13 ディレクトリーローカル変数
	`dir-locals-set-class-variables`	12.13 ディレクトリーローカル変数
	`dir-locals-set-directory-class`	12.13 ディレクトリーローカル変数
	directional overrides	39.26 双方向テキストの表示
	directory file name	25.9.3 ディレクトリーの名前
	directory local variables	12.13 ディレクトリーローカル変数
	directory name	25.9.3 ディレクトリーの名前
	directory part (of file name)	25.9.1 ファイル名の構成要素
	`directory-abbrev-alist`	25.9.3 ディレクトリーの名前
	`directory-file-name`	25.9.3 ディレクトリーの名前
	`directory-files`	25.10 ディレクトリーのコンテンツ
	`directory-files-and-attributes`	25.10 ディレクトリーのコンテンツ
	`directory-files-recursively`	25.10 ディレクトリーのコンテンツ
	`directory-name-p`	25.9.3 ディレクトリーの名前
	directory-oriented functions	25.10 ディレクトリーのコンテンツ
	`dired-kept-versions`	26.1.3 番号つきバックアップファイルの作成と削除
	`disable-command`	21.14 コマンドの無効化
	`disable-point-adjustment`	21.6 コマンド後のポイントの調整
	`disable-theme`	15.6 カスタムテーマ
	`disabled`	21.14 コマンドの無効化
	disabled command	21.14 コマンドの無効化
	`disabled-command-function`	21.14 コマンドの無効化
	disabling multibyte	33.2 マルチバイト文字の無効化
	disabling undo	32.10 アンドゥリストの保守
	`disassemble`	17.8 逆アセンブルされたバイトコード
	disassembled byte-code	17.8 逆アセンブルされたバイトコード
	`discard-input`	21.8.6 その他のイベント入力の機能
	discarding input	21.8.6 その他のイベント入力の機能
	dispatch of methods for generic function	13.8 Generic Functions
	`display (overlay property)`	39.9.2 オーバーレイのプロパティ
	`display (text property)`	39.16 `display`プロパティ
	display action	28.13 表示するウィンドウの選択
	display area	29.3.1 Frame Layout
	display feature testing	29.25 ディスプレー機能のテスト
	display margins	39.16.5 マージン内への表示
	display message in echo area	39.4.1 エコーエリアへのメッセージの表示
	display name on X	29.2 複数の端末
	display origin	29.3.1 Frame Layout
	display properties, and bidi reordering of text	39.26 双方向テキストの表示
	`display` property, and point display	21.6 コマンド後のポイントの調整
	display property, unsafe evaluation	39.16 `display`プロパティ
	display specification	39.16 `display`プロパティ
	display table	39.22.2 ディスプレーテーブル
	`display, a frame parameter`	29.4.3.1 基本パラメーター
	display, abstract	39.20 抽象的なディスプレー
	display, arbitrary objects	39.20 抽象的なディスプレー
	`display-backing-store`	29.25 ディスプレー機能のテスト
	`display-buffer`	28.13 表示するウィンドウの選択
	`display-buffer-alist`	28.13 表示するウィンドウの選択
	`display-buffer-at-bottom`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-base-action`	28.13 表示するウィンドウの選択
	`display-buffer-below-selected`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-fallback-action`	28.13 表示するウィンドウの選択
	`display-buffer-in-atom-window`	28.20 Atomic Windows
	`display-buffer-in-child-frame`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-in-previous-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-in-side-window`	28.19.1 Displaying Buffers in Side Windows
	`display-buffer-no-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-overriding-action`	28.13 表示するウィンドウの選択
	`display-buffer-pop-up-frame`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-pop-up-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-reuse-mode-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-reuse-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-same-window`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-use-some-frame`	28.14 `display-buffer`にたいするアクション関数
	`display-buffer-use-some-window`	28.14 `display-buffer`にたいするアクション関数
	`display-color-cells`	29.25 ディスプレー機能のテスト
	`display-color-p`	29.25 ディスプレー機能のテスト
	`display-completion-list`	20.6.3 補完を行うミニバッファーコマンド
	`display-delayed-warnings`	39.5.4 遅延された警告
	`display-graphic-p`	29.25 ディスプレー機能のテスト
	`display-grayscale-p`	29.25 ディスプレー機能のテスト
	`display-images-p`	29.25 ディスプレー機能のテスト
	`display-message-or-buffer`	39.4.1 エコーエリアへのメッセージの表示
	`display-mm-dimensions-alist`	29.25 ディスプレー機能のテスト
	`display-mm-height`	29.25 ディスプレー機能のテスト
	`display-mm-width`	29.25 ディスプレー機能のテスト
	`display-monitor-attributes-list`	29.2 複数の端末
	`display-mouse-p`	29.25 ディスプレー機能のテスト
	`display-pixel-height`	29.25 ディスプレー機能のテスト
	`display-pixel-width`	29.25 ディスプレー機能のテスト
	`display-planes`	29.25 ディスプレー機能のテスト
	`display-popup-menus-p`	29.25 ディスプレー機能のテスト
	`display-save-under`	29.25 ディスプレー機能のテスト
	`display-screens`	29.25 ディスプレー機能のテスト
	`display-selections-p`	29.25 ディスプレー機能のテスト
	display-start position	28.22 ウィンドウの開始位置と終了位置
	`display-supports-face-attributes-p`	29.25 ディスプレー機能のテスト
	`display-table-slot`	39.22.2 ディスプレーテーブル
	`display-type, a frame parameter`	29.4.3.1 基本パラメーター
	`display-visual-class`	29.25 ディスプレー機能のテスト
	`display-warning`	39.5.1 警告の基礎
	displaying a buffer	28.12 ウィンドウ内のバッファーへの切り替え
	displaying faces	39.12.4 フェイスの表示
	displays, multiple	29.2 複数の端末
	distinguish interactive calls	21.4 interactiveな呼び出しの区別
	`dnd-protocol-alist`	29.21 ドラッグアンドドロップ
	`do-auto-save`	26.2 自動保存
	`DOC` (documentation) file	24.1 ドキュメントの基礎
	`doc, customization keyword`	15.4.4 型キーワード
	`doc-directory`	24.2 ドキュメント文字列へのアクセス
	Document Object Model	32.28.1 Document Object Model
	`documentation`	24.2 ドキュメント文字列へのアクセス
	documentation conventions	24.1 ドキュメントの基礎
	documentation for major mode	23.2.3 メジャーモードでのヘルプ入手
	documentation notation	1.3.3 評価の表記
	documentation of function	13.2.4 関数のドキュメント文字列
	documentation strings	24 ドキュメント
	documentation strings, conventions and tips	D.6 ドキュメント文字列のヒント
	documentation, keys in	24.3 ドキュメント内でのキーバインディングの置き換え
	`documentation-property`	24.2 ドキュメント文字列へのアクセス
	`dolist`	11.4 繰り返し
	DOM	32.28.1 Document Object Model
	`dom-node`	32.28.1 Document Object Model
	`dotimes`	11.4 繰り返し
	`dotimes-with-progress-reporter`	39.4.2 処理の進捗レポート
	dotted list	5.1 リストとコンスセル
	dotted lists (Edebug)	18.2.15.2 仕様リスト
	dotted pair notation	2.3.6.2 ドットペア表記
	double-click events	21.7.7 リピートイベント
	`double-click-fuzz`	21.7.7 リピートイベント
	`double-click-time`	21.7.7 リピートイベント
	double-quote in strings	2.3.8.1 文字列の構文
	`down-list`	30.2.6 バランスのとれたカッコを越えた移動
	`downcase`	4.8 Lispでの大文字小文字変換
	`downcase-region`	32.18 大文字小文字の変更
	`downcase-word`	32.18 大文字小文字の変更
	downcasing in `lookup-key`	21.8.1 キーシーケンス入力
	drag and drop	29.21 ドラッグアンドドロップ
	drag event	21.7.5 ドラッグイベント
	`drag-internal-border, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	`drag-n-drop` event	21.7.10 その他のシステムイベント
	`drag-with-header-line, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	`drag-with-mode-line, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	dribble file	40.13.2 入力の記録
	`dump-emacs`	E.1 Emacsのビルド
	dumping Emacs	E.1 Emacsのビルド
	dynamic binding	12.10 変数のバインディングのスコーピングルール
	dynamic extent	12.10 変数のバインディングのスコーピングルール
	dynamic libraries	40.21 動的にロードされるライブラリー
	dynamic loading of documentation	17.3 ドキュメント文字列とコンパイル
	dynamic loading of functions	17.4 個別関数のダイナミックロード
	dynamic modules	16.11 Emacs Dynamic Modules
	dynamic scope	12.10 変数のバインディングのスコーピングルール
	`dynamic-library-alist`	40.21 動的にロードされるライブラリー

E
	eager macro expansion	16.1 プログラムがロードを行う方法
	`easy-menu-define`	22.17.8 easy-menu
	`easy-mmode-define-minor-mode`	23.3.3 マイナーモードの定義
	echo area	39.4 エコーエリア
	echo area customization	39.4.4 エコーエリアのカスタマイズ
	`echo-area-clear-hook`	39.4.4 エコーエリアのカスタマイズ
	`echo-keystrokes`	39.4.4 エコーエリアのカスタマイズ
	`edebug`	18.2.6.3 ソースブレークポイント
	Edebug debugging facility	18.2 Edebug
	Edebug execution modes	18.2.3 Edebugの実行モード
	Edebug specification list	18.2.15.2 仕様リスト
	edebug, failure to instrument	18.2.2 Edebugのためのインストルメント
	`edebug-all-defs`	18.2.16 Edebugのオプション
	`edebug-all-forms`	18.2.16 Edebugのオプション
	`edebug-continue-kbd-macro`	18.2.16 Edebugのオプション
	`edebug-defun`	18.2.2 Edebugのためのインストルメント
	`edebug-display-freq-count`	18.2.13 カバレッジテスト
	`edebug-eval-macro-args`	18.2.15.1 マクロ呼び出しのインストルメント
	`edebug-eval-macro-args`	18.2.16 Edebugのオプション
	`edebug-eval-top-level-form`	18.2.2 Edebugのためのインストルメント
	`edebug-global-break-condition`	18.2.16 Edebugのオプション
	`edebug-initial-mode`	18.2.16 Edebugのオプション
	`edebug-max-depth`	18.2.14.1 停止するかどうかのチェック
	`edebug-on-error`	18.2.16 Edebugのオプション
	`edebug-on-quit`	18.2.16 Edebugのオプション
	`edebug-print-circle`	18.2.11 Edebugでのプリント
	`edebug-print-circle`	18.2.16 Edebugのオプション
	`edebug-print-length`	18.2.11 Edebugでのプリント
	`edebug-print-length`	18.2.16 Edebugのオプション
	`edebug-print-level`	18.2.11 Edebugでのプリント
	`edebug-print-level`	18.2.16 Edebugのオプション
	`edebug-print-trace-after`	18.2.12 トレースバッファー
	`edebug-print-trace-before`	18.2.12 トレースバッファー
	`edebug-save-displayed-buffer-points`	18.2.16 Edebugのオプション
	`edebug-save-windows`	18.2.16 Edebugのオプション
	`edebug-set-global-break-condition`	18.2.6.2 グローバルなブレーク条件
	`edebug-set-initial-mode`	18.2.3 Edebugの実行モード
	`edebug-setup-hook`	18.2.16 Edebugのオプション
	`edebug-sit-for-seconds`	18.2.3 Edebugの実行モード
	`edebug-sit-for-seconds`	18.2.16 Edebugのオプション
	`edebug-sit-on-break`	18.2.16 Edebugのオプション
	`edebug-temp-display-freq-count`	18.2.13 カバレッジテスト
	`edebug-test-coverage`	18.2.16 Edebugのオプション
	`edebug-trace`	18.2.16 Edebugのオプション
	`edebug-trace`	18.2.12 トレースバッファー
	`edebug-tracing`	18.2.12 トレースバッファー
	`edebug-unwrap-results`	18.2.16 Edebugのオプション
	edge detection, images	39.17.2 イメージのディスクリプタ
	`edit-and-eval-command`	20.3 ミニバッファーでのLispオブジェクトの読み取り
	editing types	2.4 編集用の型
	editor command loop	21 コマンドループ
	`eight-bit`, a charset	33.7 文字セット
	`electric-future-map`	1.3.7.2 変数の説明例
	element (of list)	5 リスト
	elements of sequences	6.1 シーケンス
	`elp.el`	18.5 プロファイリング
	`elt`	6.1 シーケンス
	Emacs event standard notation	24.5 ヘルプメッセージの文字記述
	Emacs process run time	40.9 プロセッサーの実行時間
	`emacs`, a charset	33.7 文字セット
	`emacs-build-number`	1.4 バージョンの情報
	`emacs-build-time`	1.4 バージョンの情報
	`emacs-init-time`	40.9 プロセッサーの実行時間
	`emacs-internal coding system`	33.10.1 コーディングシステムの基本概念
	`emacs-lisp-docstring-fill-column`	D.6 ドキュメント文字列のヒント
	`emacs-major-version`	1.4 バージョンの情報
	`emacs-minor-version`	1.4 バージョンの情報
	`emacs-pid`	40.3 オペレーティングシステムの環境
	`emacs-save-session-functions`	40.18 セッションマネージャー
	`emacs-session-restore`	40.18 セッションマネージャー
	`emacs-startup-hook`	40.1.2 initファイル
	`emacs-uptime`	40.9 プロセッサーの実行時間
	`emacs-version`	1.4 バージョンの情報
	`emacs-version`	1.4 バージョンの情報
	emacsclient, getting a backtrace	18.1.1 エラーによるデバッガへのエンター
	`EMACSLOADPATH` environment variable	16.3 ライブラリー検索
	`emacs_module_init`	16.11 Emacs Dynamic Modules
	embedded widgets	39.18 Embedded Native Widgets
	empty lines, indicating	39.13.2 フリンジのインジケーター
	empty list	2.3.6.1 ボックスダイアグラムとしてのリストの描写
	empty overlay	39.9.1 オーバーレイの管理
	empty region	31.8 リージョン
	`emulation-mode-map-alists`	22.9 アクティブなキーマップの制御
	`enable-command`	21.14 コマンドの無効化
	`enable-connection-local-variables`	12.14 Connection Local Variables
	`enable-dir-local-variables`	12.13 ディレクトリーローカル変数
	`enable-local-eval`	12.12 ファイルローカル変数
	`enable-local-variables`	12.12 ファイルローカル変数
	`enable-multibyte-characters`	33.1 テキストの表現方法
	`enable-multibyte-characters`	33.2 マルチバイト文字の無効化
	`enable-recursive-minibuffers`	20.13 再帰的なミニバッファー
	`enable-theme`	15.6 カスタムテーマ
	encapsulation, ewoc	39.20 抽象的なディスプレー
	`encode-char`	33.7 文字セット
	`encode-coding-region`	33.10.7 明示的なエンコードとデコード
	`encode-coding-string`	33.10.7 明示的なエンコードとデコード
	`encode-time`	40.7 時刻の変換
	encoding file formats	25.13 ファイルのフォーマット変換
	encoding in coding systems	33.10.7 明示的なエンコードとデコード
	encrypted network connections	38.14 ネットワーク接続
	end of line in regexp	34.3.1.1 正規表現内の特殊文字
	`end-of-buffer`	30.2.3 バッファー終端への移動
	`end-of-defun`	30.2.6 バランスのとれたカッコを越えた移動
	`end-of-defun-function`	30.2.6 バランスのとれたカッコを越えた移動
	`end-of-file`	19.3 入力関数
	`end-of-line`	30.2.4 テキスト行単位の移動
	end-of-line conversion	33.10.1 コーディングシステムの基本概念
	endianness	38.20.1 データレイアウトの記述
	environment	10.1 評価の概要
	environment variable access	40.3 オペレーティングシステムの環境
	environment variables, subprocesses	38.1 サブプロセスを作成する関数
	`eobp`	32.1 ポイント周辺のテキストを調べる
	EOL conversion	33.10.1 コーディングシステムの基本概念
	eol conversion of coding system	33.10.3 Lispでのコーディングシステム
	eol type of coding system	33.10.3 Lispでのコーディングシステム
	`eolp`	32.1 ポイント周辺のテキストを調べる
	epoch	40.5 時刻
	`eq`	2.7 同等性のための述語
	`eql`	3.4 数値の比較
	`equal`	2.7 同等性のための述語
	`equal-including-properties`	2.7 同等性のための述語
	equality	2.7 同等性のための述語
	`erase-buffer`	32.6 テキストの削除
	`error`	11.6.3.1 エラーをシグナルする方法
	error cleanup	11.6.4 非ローカル脱出のクリーンアップ
	error debugging	18.1.1 エラーによるデバッガへのエンター
	error description	11.6.3.3 エラーを処理するコードの記述
	error display	39.4 エコーエリア
	error handler	11.6.3.3 エラーを処理するコードの記述
	`error` in debug	18.1.8 デバッガの呼び出し
	error message notation	1.3.5 エラーメッセージ
	error name	11.6.3.4 エラーシンボルとエラー条件
	error symbol	11.6.3.4 エラーシンボルとエラー条件
	`error-conditions`	11.6.3.4 エラーシンボルとエラー条件
	`error-message-string`	11.6.3.3 エラーを処理するコードの記述
	errors	11.6.3 エラー
	`ESC`	22.11 キー照合のための関数
	`esc-map`	22.6 プレフィクスキー
	`ESC-prefix`	22.6 プレフィクスキー
	escape (ASCII character)	2.3.3.1 基本的な文字構文
	escape characters	19.6 出力に影響する変数
	escape characters in printing	19.5 出力関数
	escape sequence	2.3.3.1 基本的な文字構文
	`eval`	10.5 eval
	eval during compilation	17.5 コンパイル中の評価
	`eval`, and debugging	18.1.9 デバッガの内部
	`eval-and-compile`	17.5 コンパイル中の評価
	`eval-buffer`	10.5 eval
	`eval-buffer (Edebug)`	18.2.2 Edebugのためのインストルメント
	`eval-current-buffer`	10.5 eval
	`eval-current-buffer (Edebug)`	18.2.2 Edebugのためのインストルメント
	`eval-defun (Edebug)`	18.2.2 Edebugのためのインストルメント
	`eval-expression (Edebug)`	18.2.2 Edebugのためのインストルメント
	`eval-expression-debug-on-error`	18.1.1 エラーによるデバッガへのエンター
	`eval-expression-print-length`	19.6 出力に影響する変数
	`eval-expression-print-level`	19.6 出力に影響する変数
	`eval-minibuffer`	20.3 ミニバッファーでのLispオブジェクトの読み取り
	`eval-region`	10.5 eval
	`eval-region (Edebug)`	18.2.2 Edebugのためのインストルメント
	`eval-when-compile`	17.5 コンパイル中の評価
	evaluated expression argument	21.2.2 `interactive`にたいするコード文字
	evaluation	10 評価
	evaluation error	12.3 ローカル変数
	evaluation list group	18.2.10 評価 List Buffer
	evaluation notation	1.3.3 評価の表記
	evaluation of buffer contents	10.5 eval
	evaluation of special forms	10.2.7 スペシャルフォーム
	`evaporate (overlay property)`	39.9.2 オーバーレイのプロパティ
	`even-window-sizes`	28.15 バッファー表示の追加オプション
	event printing	24.5 ヘルプメッセージの文字記述
	event translation	21.8.3 入力イベントの変更と変換
	event type	21.7.12 イベントの分類
	event, reading only one	21.8.2 単一イベントの読み取り
	`event-basic-type`	21.7.12 イベントの分類
	`event-click-count`	21.7.7 リピートイベント
	`event-convert-list`	21.7.12 イベントの分類
	`event-end`	21.7.13 マウスイベントへのアクセス
	`event-modifiers`	21.7.12 イベントの分類
	`event-start`	21.7.13 マウスイベントへのアクセス
	`eventp`	21.7 入力イベント
	events	21.7 入力イベント
	ewoc	39.20 抽象的なディスプレー
	`ewoc-buffer`	39.20.1 抽象ディスプレーの関数
	`ewoc-collect`	39.20.1 抽象ディスプレーの関数
	`ewoc-create`	39.20.1 抽象ディスプレーの関数
	`ewoc-data`	39.20.1 抽象ディスプレーの関数
	`ewoc-delete`	39.20.1 抽象ディスプレーの関数
	`ewoc-enter-after`	39.20.1 抽象ディスプレーの関数
	`ewoc-enter-before`	39.20.1 抽象ディスプレーの関数
	`ewoc-enter-first`	39.20.1 抽象ディスプレーの関数
	`ewoc-enter-last`	39.20.1 抽象ディスプレーの関数
	`ewoc-filter`	39.20.1 抽象ディスプレーの関数
	`ewoc-get-hf`	39.20.1 抽象ディスプレーの関数
	`ewoc-goto-next`	39.20.1 抽象ディスプレーの関数
	`ewoc-goto-node`	39.20.1 抽象ディスプレーの関数
	`ewoc-goto-prev`	39.20.1 抽象ディスプレーの関数
	`ewoc-invalidate`	39.20.1 抽象ディスプレーの関数
	`ewoc-locate`	39.20.1 抽象ディスプレーの関数
	`ewoc-location`	39.20.1 抽象ディスプレーの関数
	`ewoc-map`	39.20.1 抽象ディスプレーの関数
	`ewoc-next`	39.20.1 抽象ディスプレーの関数
	`ewoc-nth`	39.20.1 抽象ディスプレーの関数
	`ewoc-prev`	39.20.1 抽象ディスプレーの関数
	`ewoc-refresh`	39.20.1 抽象ディスプレーの関数
	`ewoc-set-data`	39.20.1 抽象ディスプレーの関数
	`ewoc-set-hf`	39.20.1 抽象ディスプレーの関数
	examining text properties	32.19.1 テキストプロパティを調べる
	examining the `interactive` form	21.2.1 `interactive`の使用
	examining windows	28.11 バッファーとウィンドウ
	examples of using `interactive`	21.2.3 `interactive`の使用例
	excess close parentheses	18.3.2 過剰な閉カッコ
	excess open parentheses	18.3.1 過剰な開カッコ
	excursion	30.3 エクスカーション
	`exec-directory`	38.1 サブプロセスを作成する関数
	`exec-path`	38.1 サブプロセスを作成する関数
	`exec-suffixes`	38.1 サブプロセスを作成する関数
	`executable-find`	25.6.6 標準的な場所へのファイルの配置
	execute program	38.1 サブプロセスを作成する関数
	execute with prefix argument	21.3 interactiveな呼び出し
	`execute-extended-command`	21.3 interactiveな呼び出し
	`execute-kbd-macro`	21.16 キーボードマクロ
	`executing-kbd-macro`	21.16 キーボードマクロ
	execution speed	D.4 コンパイル済みコードを高速化ためのヒント
	`exit`	21.13 再帰編集
	exit recursive editing	21.13 再帰編集
	`exit-minibuffer`	20.10 ミニバッファーのコマンド
	`exit-recursive-edit`	21.13 再帰編集
	exiting Emacs	40.2 Emacsからの脱出
	`exp`	3.9 標準的な数学関数
	`expand-abbrev`	36.4 略語の照会と展開
	`expand-file-name`	25.9.4 ファイル名を展開する関数
	expanding abbrevs	36.4 略語の照会と展開
	expansion of file names	25.9.4 ファイル名を展開する関数
	expansion of macros	14.2 マクロ呼び出しの展開
	explicit selective display	39.7 選択的な表示
	`explicit-name, a frame parameter`	29.4.3.1 基本パラメーター
	expression	10.1 評価の概要
	`expt`	3.9 標準的な数学関数
	extended file attributes	25.6.5 拡張されたファイル属性
	extended menu item	22.17.1.2 拡張メニューアイテム
	`extended-command-history`	20.4 ミニバッファーのヒストリー
	extent	12.10 変数のバインディングのスコーピングルール
	external border	29.3.1 Frame Layout
	external menu bar	29.3.1 Frame Layout
	external tool bar	29.3.1 Frame Layout
	`external-debugging-output`	19.4 出力ストリーム
	extra slots of char-table	6.6 文字テーブル
	`extra-keyboard-modifiers`	21.8.3 入力イベントの変更と変換

F
	`face (button property)`	39.19.1 ボタンのプロパティ
	`face (overlay property)`	39.9.2 オーバーレイのプロパティ
	`face (text property)`	32.19.4 特殊な意味をもつプロパティ
	face alias	39.12.6 フェイスを処理するための関数
	face attributes	39.12.1 フェイスの属性
	face attributes, access and modification	39.12.3 フェイス属性のための関数
	face codes of text	32.19.4 特殊な意味をもつプロパティ
	face merging	39.12.4 フェイスの表示
	face name	39.12 フェイス
	face remapping	39.12.5 フェイスのリマップ
	face spec	39.12.2 フェイスの定義
	`face-all-attributes`	39.12.3 フェイス属性のための関数
	`face-attribute`	39.12.3 フェイス属性のための関数
	`face-attribute-relative-p`	39.12.3 フェイス属性のための関数
	`face-background`	39.12.3 フェイス属性のための関数
	`face-bold-p`	39.12.3 フェイス属性のための関数
	`face-differs-from-default-p`	39.12.6 フェイスを処理するための関数
	`face-documentation`	24.2 ドキュメント文字列へのアクセス
	`face-documentation`	39.12.6 フェイスを処理するための関数
	`face-equal`	39.12.6 フェイスを処理するための関数
	`face-font`	39.12.3 フェイス属性のための関数
	`face-font-family-alternatives`	39.12.9 フォントの選択
	`face-font-registry-alternatives`	39.12.9 フォントの選択
	`face-font-rescale-alist`	39.12.9 フォントの選択
	`face-font-selection-order`	39.12.9 フォントの選択
	`face-foreground`	39.12.3 フェイス属性のための関数
	`face-id`	39.12.6 フェイスを処理するための関数
	`face-inverse-video-p`	39.12.3 フェイス属性のための関数
	`face-italic-p`	39.12.3 フェイス属性のための関数
	`face-list`	39.12.6 フェイスを処理するための関数
	`face-name-history`	20.4 ミニバッファーのヒストリー
	`face-remap-add-relative`	39.12.5 フェイスのリマップ
	`face-remap-remove-relative`	39.12.5 フェイスのリマップ
	`face-remap-reset-base`	39.12.5 フェイスのリマップ
	`face-remap-set-base`	39.12.5 フェイスのリマップ
	`face-remapping-alist`	39.12.5 フェイスのリマップ
	`face-spec-set`	39.12.2 フェイスの定義
	`face-stipple`	39.12.3 フェイス属性のための関数
	`face-underline-p`	39.12.3 フェイス属性のための関数
	`facemenu-keymap`	22.6 プレフィクスキー
	`facep`	39.12 フェイス
	faces	39.12 フェイス
	faces for font lock	23.6.7 Font Lockのためのフェイス
	faces, automatic choice	39.12.7 フェイスの自動割り当て
	false	1.3.2 `nil`と`t`
	`fboundp`	13.9 関数セルの内容へのアクセス
	`fceiling`	3.7 丸め処理
	`feature-unload-function`	16.9 アンロード
	`featurep`	16.7 名前つき機能
	`features`	16.7 名前つき機能
	features	16.7 名前つき機能
	`fetch-bytecode`	17.4 個別関数のダイナミックロード
	`ffloor`	3.7 丸め処理
	`field (overlay property)`	39.9.2 オーバーレイのプロパティ
	`field (text property)`	32.19.4 特殊な意味をもつプロパティ
	field numbers in format spec	4.7 文字列のフォーマット
	field width	4.7 文字列のフォーマット
	`field-beginning`	32.19.9 フィールドの定義と使用
	`field-end`	32.19.9 フィールドの定義と使用
	`field-string`	32.19.9 フィールドの定義と使用
	`field-string-no-properties`	32.19.9 フィールドの定義と使用
	fields	32.19.9 フィールドの定義と使用
	fifo data structure	6.8 オブジェクト用固定長リングの管理
	file accessibility	25.6.1 アクセシビリティのテスト
	file age	25.6.4 ファイルの属性
	file attributes	25.6.4 ファイルの属性
	file classification	25.6.2 ファイル種別の区別
	file contents, and default coding system	33.10.5 デフォルトのコーディングシステム
	file format conversion	25.13 ファイルのフォーマット変換
	file handler	25.12 特定のファイル名の“Magic”の作成
	file hard link	25.7 ファイルの名前と属性の変更
	file local variables	12.12 ファイルローカル変数
	file local variables	40.22 Security Considerations
	file locks	25.5 ファイルのロック
	file mode specification error	23.2.2 Emacsがメジャーモードを選択する方法
	file modes	25.6.1 アクセシビリティのテスト
	file modes and MS-DOS	25.6.1 アクセシビリティのテスト
	file modes, setting	25.7 ファイルの名前と属性の変更
	file modification time	25.6.4 ファイルの属性
	file name abbreviations	25.9.3 ディレクトリーの名前
	file name completion subroutines	25.9.6 ファイル名の補完
	file name of buffer	27.4 バッファーのファイル名
	file name of directory	25.9.3 ディレクトリーの名前
	file name, and default coding system	33.10.5 デフォルトのコーディングシステム
	file names	25.9 ファイルの名前
	file names in directory	25.10 ディレクトリーのコンテンツ
	file names, trailing whitespace	25.6 ファイルの情報
	file notifications	40.20 ファイル変更による通知
	file open error	25.1.2 visitのためのサブルーチン
	file permissions	25.6.1 アクセシビリティのテスト
	file permissions, setting	25.7 ファイルの名前と属性の変更
	file with multiple names	25.7 ファイルの名前と属性の変更
	file, information about	25.6 ファイルの情報
	`file-accessible-directory-p`	25.6.1 アクセシビリティのテスト
	`file-acl`	25.6.5 拡張されたファイル属性
	`file-already-exists`	25.7 ファイルの名前と属性の変更
	`file-attributes`	25.6.4 ファイルの属性
	`file-chase-links`	25.6.3 本当の名前
	`file-coding-system-alist`	33.10.5 デフォルトのコーディングシステム
	`file-directory-p`	25.6.2 ファイル種別の区別
	`file-equal-p`	25.6.3 本当の名前
	`file-error`	16.1 プログラムがロードを行う方法
	`file-executable-p`	25.6.1 アクセシビリティのテスト
	`file-exists-p`	25.6.1 アクセシビリティのテスト
	`file-expand-wildcards`	25.10 ディレクトリーのコンテンツ
	`file-extended-attributes`	25.6.5 拡張されたファイル属性
	`file-in-directory-p`	25.6.3 本当の名前
	`file-local-copy`	25.12 特定のファイル名の“Magic”の作成
	`file-local-name`	25.12 特定のファイル名の“Magic”の作成
	`file-local-variables-alist`	12.12 ファイルローカル変数
	`file-locked`	25.5 ファイルのロック
	`file-locked-p`	25.5 ファイルのロック
	`file-modes`	25.6.1 アクセシビリティのテスト
	`file-modes-symbolic-to-number`	25.7 ファイルの名前と属性の変更
	file-name encoding, MS-Windows	33.10.2 エンコーディングとI/O
	`file-name-absolute-p`	25.9.2 絶対ファイル名と相対ファイル名
	`file-name-all-completions`	25.9.6 ファイル名の補完
	`file-name-as-directory`	25.9.3 ディレクトリーの名前
	`file-name-base`	25.9.1 ファイル名の構成要素
	`file-name-case-insensitive-p`	25.6.3 本当の名前
	`file-name-coding-system`	33.10.2 エンコーディングとI/O
	`file-name-completion`	25.9.6 ファイル名の補完
	`file-name-directory`	25.9.1 ファイル名の構成要素
	`file-name-extension`	25.9.1 ファイル名の構成要素
	`file-name-handler-alist`	25.12 特定のファイル名の“Magic”の作成
	`file-name-history`	20.4 ミニバッファーのヒストリー
	`file-name-nondirectory`	25.9.1 ファイル名の構成要素
	`file-name-quote`	25.9.4 ファイル名を展開する関数
	`file-name-quoted-p`	25.9.4 ファイル名を展開する関数
	`file-name-sans-extension`	25.9.1 ファイル名の構成要素
	`file-name-sans-versions`	25.9.1 ファイル名の構成要素
	`file-name-unquote`	25.9.4 ファイル名を展開する関数
	`file-newer-than-file-p`	25.6.4 ファイルの属性
	`file-newest-backup`	26.1.4 バックアップファイルの命名
	`file-nlinks`	25.6.4 ファイルの属性
	`file-notify-add-watch`	40.20 ファイル変更による通知
	`file-notify-rm-watch`	40.20 ファイル変更による通知
	`file-notify-valid-p`	40.20 ファイル変更による通知
	`file-ownership-preserved-p`	25.6.1 アクセシビリティのテスト
	`file-precious-flag`	25.2 バッファーの保存
	`file-readable-p`	25.6.1 アクセシビリティのテスト
	`file-regular-p`	25.6.2 ファイル種別の区別
	`file-relative-name`	25.9.2 絶対ファイル名と相対ファイル名
	`file-remote-p`	25.12 特定のファイル名の“Magic”の作成
	`file-selinux-context`	25.6.5 拡張されたファイル属性
	`file-supersession`	27.6 バッファーの変更 Time
	`file-symlink-p`	25.6.2 ファイル種別の区別
	`file-truename`	25.6.3 本当の名前
	`file-writable-p`	25.6.1 アクセシビリティのテスト
	`filepos-to-bufferpos`	33.1 テキストの表現方法
	`fill-column`	32.12 fillのマージン
	`fill-context-prefix`	32.13 Adaptive Fillモード
	`fill-forward-paragraph-function`	32.11 fill
	`fill-individual-paragraphs`	32.11 fill
	`fill-individual-varying-indent`	32.11 fill
	`fill-nobreak-predicate`	32.12 fillのマージン
	`fill-paragraph`	32.11 fill
	`fill-paragraph-function`	32.11 fill
	`fill-prefix`	32.12 fillのマージン
	`fill-region`	32.11 fill
	`fill-region-as-paragraph`	32.11 fill
	`fill-separate-heterogeneous-words-with-space`	32.11 fill
	`fillarray`	6.3 配列を操作する関数
	filling text	32.11 fill
	filling, automatic	32.14 オートfill
	filter function	38.9.2 プロセスのフィルター関数
	filter multibyte flag, of process	38.9.3 プロセス出力のデコード
	`filter-buffer-substring`	32.2 バッファーのコンテンツを調べる
	`filter-buffer-substring-function`	32.2 バッファーのコンテンツを調べる
	`filter-buffer-substring-functions`	32.2 バッファーのコンテンツを調べる
	filtering killed text	32.8.2 killリングのための関数
	filtering sequences	6.1 シーケンス
	find file in path	25.6.6 標準的な場所へのファイルの配置
	find library	16.3 ライブラリー検索
	`find-auto-coding`	33.10.5 デフォルトのコーディングシステム
	`find-backup-file-name`	26.1.4 バックアップファイルの命名
	`find-buffer-visiting`	27.4 バッファーのファイル名
	`find-charset-region`	33.8 文字セットのスキャン
	`find-charset-string`	33.8 文字セットのスキャン
	`find-coding-systems-for-charsets`	33.10.3 Lispでのコーディングシステム
	`find-coding-systems-region`	33.10.3 Lispでのコーディングシステム
	`find-coding-systems-string`	33.10.3 Lispでのコーディングシステム
	`find-file`	25.1.1 ファイルをvisitする関数
	`find-file-hook`	25.1.1 ファイルをvisitする関数
	`find-file-literally`	25.1.1 ファイルをvisitする関数
	`find-file-literally`	25.1.1 ファイルをvisitする関数
	`find-file-name-handler`	25.12 特定のファイル名の“Magic”の作成
	`find-file-noselect`	25.1.1 ファイルをvisitする関数
	`find-file-not-found-functions`	25.1.1 ファイルをvisitする関数
	`find-file-other-window`	25.1.1 ファイルをvisitする関数
	`find-file-read-only`	25.1.1 ファイルをvisitする関数
	`find-file-wildcards`	25.1.1 ファイルをvisitする関数
	`find-font`	39.12.12 低レベルのフォント表現
	`find-image`	39.17.8 イメージの定義
	`find-operation-coding-system`	33.10.5 デフォルトのコーディングシステム
	`find-word-boundary-function-table`	30.2.2 単語単位の移動
	finding files	25.1 ファイルのvisit
	finding windows	28.10 ウィンドウのサイクル順
	`first-change-hook`	32.30 フックの変更
	`fit-frame-to-buffer`	28.4 ウィンドウのリサイズ
	`fit-frame-to-buffer`	28.4 ウィンドウのリサイズ
	`fit-frame-to-buffer-margins`	28.4 ウィンドウのリサイズ
	`fit-frame-to-buffer-margins, a frame parameter`	29.4.3.3 サイズのパラメーター
	`fit-frame-to-buffer-sizes`	28.4 ウィンドウのリサイズ
	`fit-frame-to-buffer-sizes, a frame parameter`	29.4.3.3 サイズのパラメーター
	`fit-window-to-buffer`	28.4 ウィンドウのリサイズ
	`fit-window-to-buffer-horizontally`	28.4 ウィンドウのリサイズ
	fixed-size window	28.3 ウィンドウのサイズ
	`fixup-whitespace`	32.7 ユーザーレベルの削除コマンド
	flags in format specifications	4.7 文字列のフォーマット
	`float`	3.5 数値の変換
	`float-e`	3.9 標準的な数学関数
	`float-output-format`	19.6 出力に影響する変数
	`float-pi`	3.9 標準的な数学関数
	`float-time`	40.5 時刻
	floating-point functions	3.9 標準的な数学関数
	`floatp`	3.3 数値のための述語
	`floats-consed`	E.5 メモリー使用量
	`floor`	3.5 数値の変換
	flowcontrol, in serial connections	38.19 シリアルポートとの対話
	flushing input	21.8.6 その他のイベント入力の機能
	`fmakunbound`	13.9 関数セルの内容へのアクセス
	`fn` in function’s documentation string	16.5 autoload
	focus event	21.7.9 フォーカスイベント
	`focus-follows-mouse`	29.10 入力のフォーカス
	`focus-in-hook`	29.10 入力のフォーカス
	`focus-in-hook`	Appendix H 標準的なフック
	`focus-out-hook`	29.10 入力のフォーカス
	`focus-out-hook`	Appendix H 標準的なフック
	follow links	32.19.8 クリック可能なテキストの定義
	`follow-link (button property)`	39.19.1 ボタンのプロパティ
	`follow-link (text or overlay property)`	32.19.8 クリック可能なテキストの定義
	`following-char`	32.1 ポイント周辺のテキストを調べる
	font and color, frame parameters	29.4.3.10 フォントとカラーのパラメーター
	font entity	39.12.12 低レベルのフォント表現
	font information for layout	39.12.12 低レベルのフォント表現
	font lock faces	23.6.7 Font Lockのためのフェイス
	Font Lock mode	23.6 Font Lockモード
	font lookup	39.12.10 フォントの照会
	font object	39.12.12 低レベルのフォント表現
	font property	39.12.12 低レベルのフォント表現
	font registry	39.12.12 低レベルのフォント表現
	font selection	39.12.9 フォントの選択
	font spec	39.12.12 低レベルのフォント表現
	`font, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`font-at`	39.12.12 低レベルのフォント表現
	`font-backend, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`font-face-attributes`	39.12.12 低レベルのフォント表現
	`font-family-list`	39.12.1 フェイスの属性
	`font-get`	39.12.12 低レベルのフォント表現
	`font-info`	39.12.12 低レベルのフォント表現
	`font-lock-add-keywords`	23.6.3 検索ベースのフォント化のカスタマイズ
	`font-lock-builtin-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-comment-delimiter-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-comment-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-constant-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-defaults`	23.6.1 Font Lockの基礎
	`font-lock-doc-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-ensure &optional beg end`	23.6.1 Font Lockの基礎
	`font-lock-ensure-function`	23.6.4 Font Lockのその他の変数
	`font-lock-extend-after-change-region-function`	23.6.9.2 バッファー変更後のリージョンのフォント化
	`font-lock-extra-managed-props`	23.6.4 Font Lockのその他の変数
	`font-lock-face (text property)`	32.19.4 特殊な意味をもつプロパティ
	`font-lock-flush &optional beg end`	23.6.1 Font Lockの基礎
	`font-lock-flush-function`	23.6.4 Font Lockのその他の変数
	`font-lock-fontify-buffer`	23.6.1 Font Lockの基礎
	`font-lock-fontify-buffer-function`	23.6.4 Font Lockのその他の変数
	`font-lock-fontify-region beg end &optional loudly`	23.6.1 Font Lockの基礎
	`font-lock-fontify-region-function`	23.6.4 Font Lockのその他の変数
	`font-lock-function-name-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-keyword-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-keywords`	23.6.2 検索ベースのフォント化
	`font-lock-keywords-case-fold-search`	23.6.2 検索ベースのフォント化
	`font-lock-keywords-only`	23.6.8 構文的なFont Lock
	`font-lock-mark-block-function`	23.6.4 Font Lockのその他の変数
	`font-lock-multiline`	23.6.9.1 複数行のFont Lock
	`font-lock-negation-char-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-preprocessor-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-remove-keywords`	23.6.3 検索ベースのフォント化のカスタマイズ
	`font-lock-string-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-syntactic-face-function`	23.6.8 構文的なFont Lock
	`font-lock-syntax-table`	23.6.8 構文的なFont Lock
	`font-lock-type-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-unfontify-buffer`	23.6.1 Font Lockの基礎
	`font-lock-unfontify-buffer-function`	23.6.4 Font Lockのその他の変数
	`font-lock-unfontify-region beg end`	23.6.1 Font Lockの基礎
	`font-lock-unfontify-region-function`	23.6.4 Font Lockのその他の変数
	`font-lock-variable-name-face`	23.6.7 Font Lockのためのフェイス
	`font-lock-warning-face`	23.6.7 Font Lockのためのフェイス
	`font-put`	39.12.12 低レベルのフォント表現
	`font-spec`	39.12.12 低レベルのフォント表現
	`font-xlfd-name`	39.12.12 低レベルのフォント表現
	`fontification-functions`	39.12.7 フェイスの自動割り当て
	`fontified (text property)`	32.19.4 特殊な意味をもつプロパティ
	`fontp`	39.12.12 低レベルのフォント表現
	fontset	39.12.11 フォントセット
	`foo`	1.3.7.1 関数の説明例
	`for`	14.5.2 マクロ引数の多重評価
	force coding system for operation	33.10.6 単一の操作にたいするコーディングシステムの指定
	force entry to debugger	18.1.5 明示的なデバッガへのエントリー
	`force-mode-line-update`	23.4.1 モードラインの基礎
	`force-window-update`	39.2 強制的な再表示
	forcing redisplay	39.2 強制的な再表示
	`foreground-color, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	form	10.1 評価の概要
	`format`	4.7 文字列のフォーマット
	format definition	25.13.2 ラウンドトリップ仕様
	format of gnutls cryptography inputs	32.27.1 Format of GnuTLS Cryptography Inputs
	format of keymaps	22.3 キーマップのフォーマット
	format specification	4.7 文字列のフォーマット
	`format, customization keyword`	15.4.4 型キーワード
	`format-alist`	25.13.2 ラウンドトリップ仕様
	`format-find-file`	25.13.2 ラウンドトリップ仕様
	`format-insert-file`	25.13.2 ラウンドトリップ仕様
	`format-message`	4.7 文字列のフォーマット
	`format-mode-line`	23.4.8 モードラインのフォーマットのエミュレート
	`format-network-address`	38.18 その他のネットワーク機能
	`format-seconds`	40.8 時刻のパースとフォーマット
	`format-time-string`	40.8 時刻のパースとフォーマット
	`format-write-file`	25.13.2 ラウンドトリップ仕様
	formatting strings	4.7 文字列のフォーマット
	formatting time values	40.8 時刻のパースとフォーマット
	formfeed	2.3.3.1 基本的な文字構文
	`forward-button`	39.19.5 ボタンのためのバッファーコマンド
	`forward-char`	30.2.1 文字単位の移動
	`forward-comment`	35.6.1 パースにもとづくモーションコマンド
	`forward-line`	30.2.4 テキスト行単位の移動
	`forward-list`	30.2.6 バランスのとれたカッコを越えた移動
	`forward-sexp`	30.2.6 バランスのとれたカッコを越えた移動
	`forward-to-indentation`	32.17.6 インデントにもとづくモーションコマンド
	`forward-word`	30.2.2 単語単位の移動
	`forward-word-strictly`	30.2.2 単語単位の移動
	frame	29 フレーム
	frame configuration	29.13 フレーム構成
	frame creation	29.1 フレームの作成
	frame geometry	29.3 Frame Geometry
	frame height ratio	29.4.3.3 サイズのパラメーター
	frame interaction parameters	29.4.3.6 Frame Interaction Parameters
	frame layout	29.3.1 Frame Layout
	frame layout parameters	29.4.3.4 レイアウトのパラメーター
	frame parameters	29.4 フレームのパラメーター
	frame parameters for windowed displays	29.4.3 ウィンドウフレームパラメーター
	frame position	29.3 Frame Geometry
	frame position	29.3.3 Frame Position
	frame position	29.4.3.2 位置のパラメーター
	frame position changes, a hook	29.3.3 Frame Position
	frame size	29.3 Frame Geometry
	frame size	29.3.4 Frame Size
	frame stacking order	29.12 Raising, Lowering and Restacking Frames
	frame title	29.6 フレームのタイトル
	frame visibility	29.11 フレームの可視性
	frame width ratio	29.4.3.3 サイズのパラメーター
	frame without a minibuffer	29.9 ミニバッファーとフレーム
	frame Z-order	29.12 Raising, Lowering and Restacking Frames
	frame, which buffers to display	29.4.3.5 バッファーのパラメーター
	`frame-alpha-lower-limit`	29.4.3.10 フォントとカラーのパラメーター
	`frame-ancestor-p`	29.14 Child Frames
	`frame-auto-hide-function`	28.18 ウィンドウのquit
	`frame-char-height`	29.3.2 Frame Font
	`frame-char-width`	29.3.2 Frame Font
	`frame-current-scroll-bars`	39.14 スクロールバー
	`frame-edges`	29.3.1 Frame Layout
	`frame-first-window`	28.2 ウィンドウとフレーム
	`frame-geometry`	29.3.1 Frame Layout
	`frame-height`	29.3.4 Frame Size
	`frame-inherited-parameters`	29.1 フレームの作成
	`frame-inhibit-implied-resize`	29.3.5 Implied Frame Resizing
	`frame-inner-height`	29.3.4 Frame Size
	`frame-inner-width`	29.3.4 Frame Size
	`frame-list`	29.8 すべてのフレームを探す
	`frame-list-z-order`	29.8 すべてのフレームを探す
	`frame-live-p`	29.7 フレームの削除
	`frame-monitor-attributes`	29.2 複数の端末
	`frame-native-height`	29.3.4 Frame Size
	`frame-native-width`	29.3.4 Frame Size
	`frame-outer-height`	29.3.4 Frame Size
	`frame-outer-width`	29.3.4 Frame Size
	`frame-parameter`	29.4.1 フレームパラメーターへのアクセス
	`frame-parameters`	29.4.1 フレームパラメーターへのアクセス
	`frame-parent`	29.14 Child Frames
	`frame-pointer-visible-p`	29.16 マウスの位置
	`frame-position`	29.3.3 Frame Position
	frame-relative coordinate	28.26 座標とウィンドウ
	`frame-resize-pixelwise`	29.3.4 Frame Size
	`frame-restack`	29.12 Raising, Lowering and Restacking Frames
	`frame-root-window`	28.2 ウィンドウとフレーム
	`frame-scroll-bar-height`	39.14 スクロールバー
	`frame-scroll-bar-width`	39.14 スクロールバー
	`frame-selected-window`	28.9 ウィンドウの選択
	`frame-size-changed-p`	29.3.4 Frame Size
	`frame-terminal`	29 フレーム
	`frame-text-height`	29.3.4 Frame Size
	`frame-text-width`	29.3.4 Frame Size
	`frame-title-format`	29.6 フレームのタイトル
	`frame-visible-p`	29.11 フレームの可視性
	`frame-width`	29.3.4 Frame Size
	`framep`	29 フレーム
	frames, scanning all	29.8 すべてのフレームを探す
	free list	E.3 ガーベージコレクション
	free variable	12.10.4 レキシカルバインディングの使用
	free variable, byte-compiler warning	17.6 コンパイラーのエラー
	frequency counts	18.2.13 カバレッジテスト
	`frexp`	3.2 浮動小数点数の基礎
	fringe bitmaps	39.13.4 フリンジのビットマップ
	fringe bitmaps, customizing	39.13.5 フリンジビットマップのカスタマイズ
	fringe cursors	39.13.3 フリンジのカーソルFringe Cursors
	fringe indicators	39.13.2 フリンジのインジケーター
	`fringe-bitmaps-at-pos`	39.13.4 フリンジのビットマップ
	`fringe-cursor-alist`	39.13.3 フリンジのカーソルFringe Cursors
	`fringe-indicator-alist`	39.13.2 フリンジのインジケーター
	fringes	39.13 フリンジ
	fringes, and empty line indication	39.13.2 フリンジのインジケーター
	`fringes-outside-margins`	39.13.1 フリンジのサイズと位置
	`fround`	3.7 丸め処理
	`fset`	13.9 関数セルの内容へのアクセス
	`ftp-login`	11.6.4 非ローカル脱出のクリーンアップ
	`ftruncate`	3.7 丸め処理
	full keymap	22.3 キーマップのフォーマット
	full-height window	28.3 ウィンドウのサイズ
	full-width window	28.3 ウィンドウのサイズ
	fullboth frames	29.4.3.3 サイズのパラメーター
	fullheight frames	29.4.3.3 サイズのパラメーター
	`fullscreen, a frame parameter`	29.4.3.3 サイズのパラメーター
	`fullscreen-restore, a frame parameter`	29.4.3.3 サイズのパラメーター
	fullwidth frames	29.4.3.3 サイズのパラメーター
	`func-arity`	13.1 関数とは?
	`funcall`	13.5 関数の呼び出し
	`funcall`, and debugging	18.1.9 デバッガの内部
	`funcall-interactively`	21.3 interactiveな呼び出し
	`function`	13.7 無名関数
	function aliases	13.4 関数の定義
	function call	10.2.5 関数フォームの評価
	function call debugging	18.1.3 関数呼び出しによるデバッガへのエンター
	function cell	9.1 シンボルの構成要素
	function cell in autoload	16.5 autoload
	function declaration	13.15 コンパイラーへの定義済み関数の指示
	function definition	13.3 関数の命名
	function descriptions	1.3.7.1 関数の説明例
	function form evaluation	10.2.5 関数フォームの評価
	function input stream	19.2 入力ストリーム
	function invocation	13.5 関数の呼び出し
	function keys	21.7.2 ファンクションキー
	function name	13.3 関数の命名
	function not known to be defined, compilation warning	17.6 コンパイラーのエラー
	function output stream	19.4 出力ストリーム
	function quoting	13.7 無名関数
	function safety	13.16 安全に関数を呼び出せるかどうかの判断
	`function-documentation` property	24.1 ドキュメントの基礎
	`function-get`	9.4.1 シンボルのプロパティへのアクセス
	`function-put`	9.4.1 シンボルのプロパティへのアクセス
	functionals	13.5 関数の呼び出し
	`functionp`	13.1 関数とは?
	functions in modes	23.2.1 メジャーモードの慣習
	functions, making them interactive	21.2 コマンドの定義
	`fundamental-mode`	23.2 メジャーモード
	`fundamental-mode-abbrev-table`	36.5 標準的なabbrevテーブル

G
	gamma correction	29.4.3.10 フォントとカラーのパラメーター
	`gap-position`	27.13 バッファーのギャップ
	`gap-size`	27.13 バッファーのギャップ
	garbage collection	E.3 ガーベージコレクション
	garbage collection protection	E.7 Emacsプリミティブの記述
	`garbage-collect`	E.3 ガーベージコレクション
	`garbage-collection-messages`	E.3 ガーベージコレクション
	`gc-cons-percentage`	E.3 ガーベージコレクション
	`gc-cons-threshold`	E.3 ガーベージコレクション
	`gc-elapsed`	E.3 ガーベージコレクション
	`gcs-done`	E.3 ガーベージコレクション
	generalized variable	12.17 ジェネリック変数
	`generate-autoload-cookie`	16.5 autoload
	`generate-new-buffer`	27.9 バッファーの作成
	`generate-new-buffer-name`	27.3 バッファーの名前
	`generated-autoload-file`	16.5 autoload
	generators	11.5 Generators
	generic commands	21.2.4 コマンド候補からの選択
	generic functions	13.8 Generic Functions
	generic mode	23.2.8 ジェネリックモード
	`gensym`	9.3 シンボルの作成とintern
	geometry specification	29.4.4 ジオメトリー
	`get`	9.4.1 シンボルのプロパティへのアクセス
	`get, defcustom keyword`	15.3 カスタマイズ変数の定義
	`get-buffer`	27.3 バッファーの名前
	`get-buffer-create`	27.9 バッファーの作成
	`get-buffer-process`	38.9.1 プロセスのバッファー
	`get-buffer-window`	28.11 バッファーとウィンドウ
	`get-buffer-window-list`	28.11 バッファーとウィンドウ
	`get-buffer-xwidgets`	39.18 Embedded Native Widgets
	`get-byte`	33.5 文字コード
	`get-char-code-property`	33.6 文字のプロパティ
	`get-char-property`	32.19.1 テキストプロパティを調べる
	`get-char-property-and-overlay`	32.19.1 テキストプロパティを調べる
	`get-charset-property`	33.7 文字セット
	`get-device-terminal`	29.2 複数の端末
	`get-file-buffer`	27.4 バッファーのファイル名
	`get-internal-run-time`	40.9 プロセッサーの実行時間
	`get-largest-window`	28.10 ウィンドウのサイクル順
	`get-load-suffixes`	16.2 ロードでの拡張子
	`get-lru-window`	28.10 ウィンドウのサイクル順
	`get-mru-window`	28.10 ウィンドウのサイクル順
	`get-pos-property`	32.19.1 テキストプロパティを調べる
	`get-process`	38.6 プロセスの情報
	`get-register`	32.21 レジスター
	`get-text-property`	32.19.1 テキストプロパティを調べる
	`get-unused-category`	35.8 カテゴリー
	`get-variable-watchers`	12.9 Running a function when a variable is changed.
	`get-window-with-predicate`	28.10 ウィンドウのサイクル順
	`getenv`	40.3 オペレーティングシステムの環境
	`gethash`	8.2 ハッシュテーブルへのアクセス
	GID	40.4 ユーザーの識別
	global binding	12.3 ローカル変数
	global break condition	18.2.6.2 グローバルなブレーク条件
	global keymap	22.7 アクティブなキーマップ
	global variable	12.1 グローバル変数
	`global-abbrev-table`	36.5 標準的なabbrevテーブル
	`global-buffers-menu-map`	Appendix G 標準的なキーマップ
	`global-disable-point-adjustment`	21.6 コマンド後のポイントの調整
	`global-key-binding`	22.11 キー照合のための関数
	`global-map`	22.9 アクティブなキーマップの制御
	`global-mode-string`	23.4.4 モードラインで使用される変数
	`global-set-key`	22.15 キーのバインドのためのコマンド
	`global-unset-key`	22.15 キーのバインドのためのコマンド
	glyph	39.22.4 グリフ
	glyph code	39.22.4 グリフ
	`glyph-char`	39.22.4 グリフ
	`glyph-face`	39.22.4 グリフ
	`glyph-table`	39.22.4 グリフ
	glyphless characters	39.22.5 グリフ文字の表示
	`glyphless-char-display`	39.22.5 グリフ文字の表示
	`glyphless-char-display-control`	39.22.5 グリフ文字の表示
	gnutls cryptographic functions	32.27.2 GnuTLS Cryptographic Functions
	gnutls cryptography inputs format	32.27.1 Format of GnuTLS Cryptography Inputs
	`gnutls-ciphers`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-digests`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-hash-digest`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-hash-mac`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-macs`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-symmetric-decrypt`	32.27.2 GnuTLS Cryptographic Functions
	`gnutls-symmetric-encrypt`	32.27.2 GnuTLS Cryptographic Functions
	`goto-char`	30.2.1 文字単位の移動
	`goto-map`	22.6 プレフィクスキー
	grammar, SMIE	23.7.1.3 言語の文法の定義
	graphical display	29 フレーム
	graphical terminal	29 フレーム
	`group, customization keyword`	15.1 一般的なキーワードアイテム
	`group-gid`	40.4 ユーザーの識別
	`group-real-gid`	40.4 ユーザーの識別
	`gui-get-selection`	29.20 ウィンドウシステムによる選択
	`gui-set-selection`	29.20 ウィンドウシステムによる選択
	`gv-define-expander`	12.17.2 新たな`setf`フォーム
	`gv-define-setter`	12.17.2 新たな`setf`フォーム
	`gv-define-simple-setter`	12.17.2 新たな`setf`フォーム
	`gv-letplace`	12.17.2 新たな`setf`フォーム

H
	`hack-connection-local-variables`	12.14 Connection Local Variables
	`hack-connection-local-variables-apply`	12.14 Connection Local Variables
	`hack-dir-local-variables`	12.13 ディレクトリーローカル変数
	`hack-dir-local-variables-non-file-buffer`	12.13 ディレクトリーローカル変数
	`hack-local-variables`	12.12 ファイルローカル変数
	`hack-local-variables-hook`	12.12 ファイルローカル変数
	`handle-shift-selection`	31.7 マーク
	`handle-switch-frame`	29.10 入力のフォーカス
	handling errors	11.6.3.3 エラーを処理するコードの記述
	hardening	40.22 Security Considerations
	hash code	8.3 ハッシュの比較の定義
	hash notation	2.1 プリント表現と読み取り構文
	hash table access	8.2 ハッシュテーブルへのアクセス
	hash tables	8 ハッシュテーブル
	hash, cryptographic	32.26 チェックサムとハッシュ
	hash, cryptographic	32.27 GnuTLS Cryptography
	`hash-table-count`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-p`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-rehash-size`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-rehash-threshold`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-size`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-test`	8.4 ハッシュテーブルのためのその他関数
	`hash-table-weakness`	8.4 ハッシュテーブルのためのその他関数
	hashing	9.3 シンボルの作成とintern
	header comments	D.8 Emacsライブラリーのヘッダーの慣習
	header line (of a window)	23.4.7 ウィンドウのヘッダーライン
	`header-line` prefix key	21.8.1 キーシーケンス入力
	`header-line-format`	23.4.7 ウィンドウのヘッダーライン
	`header-line-format, a window parameter`	28.29 ウィンドウのパラメーター
	height of a line	39.11 行の高さ
	height of a window	28.3 ウィンドウのサイズ
	height spec	39.11 行の高さ
	`height, a frame parameter`	29.4.3.3 サイズのパラメーター
	help for major mode	23.2.3 メジャーモードでのヘルプ入手
	help functions	24.6 ヘルプ関数
	`help-buffer`	24.6 ヘルプ関数
	`help-char`	24.6 ヘルプ関数
	`help-command`	24.6 ヘルプ関数
	`help-echo (overlay property)`	39.9.2 オーバーレイのプロパティ
	`help-echo (text property)`	32.19.4 特殊な意味をもつプロパティ
	`help-echo` event	21.7.10 その他のシステムイベント
	`help-echo, customization keyword`	15.4.4 型キーワード
	`help-event-list`	24.6 ヘルプ関数
	`help-form`	24.6 ヘルプ関数
	`help-index (button property)`	39.19.1 ボタンのプロパティ
	`help-map`	24.6 ヘルプ関数
	`help-setup-xref`	24.6 ヘルプ関数
	`help-window-select`	24.6 ヘルプ関数
	`Helper-describe-bindings`	24.6 ヘルプ関数
	`Helper-help`	24.6 ヘルプ関数
	`Helper-help-map`	24.6 ヘルプ関数
	hex numbers	3.1 整数の基礎
	hidden buffers	27.3 バッファーの名前
	history list	20.4 ミニバッファーのヒストリー
	history of commands	21.15 コマンドのヒストリー
	`history-add-new-input`	20.4 ミニバッファーのヒストリー
	`history-delete-duplicates`	20.4 ミニバッファーのヒストリー
	`history-length`	20.4 ミニバッファーのヒストリー
	`HOME` environment variable	38.1 サブプロセスを作成する関数
	hook variables, list of	Appendix H 標準的なフック
	hooks	23.1 フック
	hooks for changing a character	32.19.4 特殊な意味をもつプロパティ
	hooks for loading	16.10 ロードのためのフック
	hooks for motion of point	32.19.4 特殊な意味をもつプロパティ
	hooks for text changes	32.30 フックの変更
	hooks for window operations	28.30 ウィンドウのスクロールと変更のためのフック
	horizontal combination	28.2 ウィンドウとフレーム
	horizontal position	32.16 列を数える
	horizontal scrolling	28.25 水平スクロール
	`horizontal-scroll-bar`	39.14 スクロールバー
	`horizontal-scroll-bar` prefix key	21.8.1 キーシーケンス入力
	`horizontal-scroll-bar-mode`	39.14 スクロールバー
	`horizontal-scroll-bars, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`horizontal-scroll-bars-available-p`	39.14 スクロールバー
	how to visit files	25.1.1 ファイルをvisitする関数
	HTML DOM	32.28.1 Document Object Model
	hyper characters	2.3.3.5 その他の文字修飾ビット
	hyperlinks in documentation strings	D.6 ドキュメント文字列のヒント

I
	`icon-left, a frame parameter`	29.4.3.2 位置のパラメーター
	`icon-name, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`icon-title-format`	29.6 フレームのタイトル
	`icon-top, a frame parameter`	29.4.3.2 位置のパラメーター
	`icon-type, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	iconified frame	29.11 フレームの可視性
	`iconify-child-frame`	29.14 Child Frames
	`iconify-frame`	29.11 フレームの可視性
	`iconify-frame` event	21.7.10 その他のシステムイベント
	`identity`	13.5 関数の呼び出し
	idle timers	40.12 アイドルタイマー
	idleness	40.12 アイドルタイマー
	IEEE floating point	3.2 浮動小数点数の基礎
	`if`	11.2 条件
	`ignore`	13.5 関数の呼び出し
	`ignore-errors`	11.6.3.3 エラーを処理するコードの記述
	`ignore-window-parameters`	28.29 ウィンドウのパラメーター
	`ignored-local-variables`	12.12 ファイルローカル変数
	image animation	39.17.10 マルチフレームのイメージ
	image cache	39.17.11 イメージキャッシュ
	image descriptor	39.17.2 イメージのディスクリプタ
	image formats	39.17.1 イメージのフォーマット
	image frames	39.17.10 マルチフレームのイメージ
	image maps	39.17.2 イメージのディスクリプタ
	image slice	39.17.9 イメージの表示
	image types	39.17.1 イメージのフォーマット
	`image-animate`	39.17.10 マルチフレームのイメージ
	`image-animate-timer`	39.17.10 マルチフレームのイメージ
	`image-cache-eviction-delay`	39.17.11 イメージキャッシュ
	`image-current-frame`	39.17.10 マルチフレームのイメージ
	`image-default-frame-delay`	39.17.10 マルチフレームのイメージ
	`image-flush`	39.17.11 イメージキャッシュ
	`image-format-suffixes`	39.17.5 ImageMagickイメージ
	`image-load-path`	39.17.8 イメージの定義
	`image-load-path-for-library`	39.17.8 イメージの定義
	`image-mask-p`	39.17.2 イメージのディスクリプタ
	`image-minimum-frame-delay`	39.17.10 マルチフレームのイメージ
	`image-multi-frame-p`	39.17.10 マルチフレームのイメージ
	`image-property`	39.17.8 イメージの定義
	`image-scaling-factor`	39.17.8 イメージの定義
	`image-show-frame`	39.17.10 マルチフレームのイメージ
	`image-size`	39.17.9 イメージの表示
	`image-type-available-p`	39.17.1 イメージのフォーマット
	`image-types`	39.17.1 イメージのフォーマット
	ImageMagick images	39.17.5 ImageMagickイメージ
	`imagemagick-enabled-types`	39.17.5 ImageMagickイメージ
	`imagemagick-types`	39.17.5 ImageMagickイメージ
	`imagemagick-types-inhibit`	39.17.5 ImageMagickイメージ
	images in buffers	39.17 イメージ
	images, support for more formats	39.17.5 ImageMagickイメージ
	Imenu	23.5 Imenu
	`imenu-add-to-menubar`	23.5 Imenu
	`imenu-case-fold-search`	23.5 Imenu
	`imenu-create-index-function`	23.5 Imenu
	`imenu-extract-index-name-function`	23.5 Imenu
	`imenu-generic-expression`	23.5 Imenu
	`imenu-prev-index-position-function`	23.5 Imenu
	`imenu-syntax-alist`	23.5 Imenu
	implicit `progn`	11.1 順序
	implied frame resizing	29.3.5 Implied Frame Resizing
	implied resizing of frame	29.3.5 Implied Frame Resizing
	inactive minibuffer	20.1 ミニバッファーの概念
	`inc`	14.1 単純なマクロの例
	indefinite extent	12.10 変数のバインディングのスコーピングルール
	`indent-according-to-mode`	32.17.2 メジャーモードが制御するインデント
	`indent-code-rigidly`	32.17.3 リージョン全体のインデント
	`indent-for-tab-command`	32.17.2 メジャーモードが制御するインデント
	`indent-line-function`	32.17.2 メジャーモードが制御するインデント
	`indent-region`	32.17.3 リージョン全体のインデント
	`indent-region-function`	32.17.3 リージョン全体のインデント
	`indent-relative`	32.17.4 前行に相対的なインデント
	`indent-relative-maybe`	32.17.4 前行に相対的なインデント
	`indent-rigidly`	32.17.3 リージョン全体のインデント
	`indent-tabs-mode`	32.17.1 インデント用のプリミティブ
	`indent-to`	32.17.1 インデント用のプリミティブ
	`indent-to-left-margin`	32.12 fillのマージン
	indentation	32.17 インデント
	indentation rules, SMIE	23.7.1.6 インデントルールの指定
	`indicate-buffer-boundaries`	39.13.2 フリンジのインジケーター
	`indicate-empty-lines`	39.13.2 フリンジのインジケーター
	indicators, fringe	39.13.2 フリンジのインジケーター
	indirect buffers	27.11 インダイレクトバッファー
	indirect specifications	18.2.15.2 仕様リスト
	`indirect-function`	10.2.4 シンボル関数インダイレクション
	`indirect-variable`	12.15 変数のエイリアス
	indirection for functions	10.2.4 シンボル関数インダイレクション
	infinite loops	18.1.2 無限ループのデバッグ
	infinite recursion	12.3 ローカル変数
	infinity	3.2 浮動小数点数の基礎
	inheritance, for faces	39.12.1 フェイスの属性
	inheritance, keymap	22.5 継承とキーマップ
	inheritance, syntax table	35.1 構文テーブルの概念
	inheritance, text property	32.19.6 テキストプロパティの粘着性
	`inhibit-default-init`	40.1.2 initファイル
	`inhibit-double-buffering, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`inhibit-eol-conversion`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`inhibit-field-text-motion`	30.2.2 単語単位の移動
	`inhibit-file-name-handlers`	25.12 特定のファイル名の“Magic”の作成
	`inhibit-file-name-operation`	25.12 特定のファイル名の“Magic”の作成
	`inhibit-iso-escape-detection`	33.10.3 Lispでのコーディングシステム
	`inhibit-local-variables-regexps`	12.12 ファイルローカル変数
	`inhibit-local-variables-regexps`	23.2.2 Emacsがメジャーモードを選択する方法
	`inhibit-message`	39.4.1 エコーエリアへのメッセージの表示
	`inhibit-modification-hooks`	32.30 フックの変更
	`inhibit-null-byte-detection`	33.10.3 Lispでのコーディングシステム
	`inhibit-point-motion-hooks`	32.19.4 特殊な意味をもつプロパティ
	`inhibit-quit`	21.11 quit
	`inhibit-read-only`	27.7 読み取り専用のバッファー
	`inhibit-read-only (text property)`	32.19.4 特殊な意味をもつプロパティ
	`inhibit-splash-screen`	40.1.1 要約: スタートアップ時のアクション順序
	`inhibit-startup-echo-area-message`	40.1.1 要約: スタートアップ時のアクション順序
	`inhibit-startup-message`	40.1.1 要約: スタートアップ時のアクション順序
	`inhibit-startup-screen`	40.1.1 要約: スタートアップ時のアクション順序
	`inhibit-x-resources`	29.24 Xリソース
	init file	40.1.2 initファイル
	`init-file-user`	40.4 ユーザーの識別
	`init.el`	40.1.2 initファイル
	`initial-buffer-choice`	40.1.1 要約: スタートアップ時のアクション順序
	`initial-environment`	40.3 オペレーティングシステムの環境
	`initial-frame-alist`	29.4.2 フレームの初期パラメーター
	`initial-major-mode`	23.2.2 Emacsがメジャーモードを選択する方法
	`initial-scratch-message`	40.1.1 要約: スタートアップ時のアクション順序
	`initial-window-system`	39.24 ウィンドウシステム
	`initial-window-system, and startup`	40.1.1 要約: スタートアップ時のアクション順序
	initialization of Emacs	40.1.1 要約: スタートアップ時のアクション順序
	`initialize, defcustom keyword`	15.3 カスタマイズ変数の定義
	inline completion	20.6.8 通常バッファーでの補完
	inline functions	13.13 インライン関数Inline Functions
	`inline-const-p`	13.4 関数の定義
	`inline-const-val`	13.4 関数の定義
	`inline-error`	13.4 関数の定義
	`inline-letevals`	13.4 関数の定義
	`inline-quote`	13.4 関数の定義
	inner edges	29.3.1 Frame Layout
	inner frame	29.3.1 Frame Layout
	inner height	29.3.1 Frame Layout
	inner size	29.3.1 Frame Layout
	inner width	29.3.1 Frame Layout
	innermost containing parentheses	35.6.3 パーサー状態
	input events	21.7 入力イベント
	input focus	29.10 入力のフォーカス
	input methods	33.11 入力メソッド
	input modes	40.13.1 入力のモード
	input stream	19.2 入力ストリーム
	`input-decode-map`	22.14 イベントシーケンス変換のためのキーマップ
	`input-method-alist`	33.11 入力メソッド
	`input-method-function`	21.8.4 入力メソッドの呼び出し
	`input-pending-p`	21.8.6 その他のイベント入力の機能
	`insert`	32.4 テキストの挿入
	`insert-abbrev-table-description`	36.1 abbrevテーブル
	`insert-and-inherit`	32.19.6 テキストプロパティの粘着性
	`insert-before-markers`	32.4 テキストの挿入
	`insert-before-markers-and-inherit`	32.19.6 テキストプロパティの粘着性
	`insert-behind-hooks (overlay property)`	39.9.2 オーバーレイのプロパティ
	`insert-behind-hooks (text property)`	32.19.4 特殊な意味をもつプロパティ
	`insert-buffer`	32.5 ユーザーレベルの挿入コマンド
	`insert-buffer-substring`	32.4 テキストの挿入
	`insert-buffer-substring-as-yank`	32.8.3 yank
	`insert-buffer-substring-no-properties`	32.4 テキストの挿入
	`insert-button`	39.19.3 ボタンの作成
	`insert-char`	32.4 テキストの挿入
	`insert-default-directory`	20.6.5 ファイル名の読み取り
	`insert-directory`	25.10 ディレクトリーのコンテンツ
	`insert-directory-program`	25.10 ディレクトリーのコンテンツ
	`insert-file-contents`	25.3 ファイルの読み込み
	`insert-file-contents-literally`	25.3 ファイルの読み込み
	`insert-for-yank`	32.8.3 yank
	`insert-image`	39.17.9 イメージの表示
	`insert-in-front-hooks (overlay property)`	39.9.2 オーバーレイのプロパティ
	`insert-in-front-hooks (text property)`	32.19.4 特殊な意味をもつプロパティ
	`insert-register`	32.21 レジスター
	`insert-sliced-image`	39.17.9 イメージの表示
	`insert-text-button`	39.19.3 ボタンの作成
	inserting killed text	32.8.4 yankのための関数
	insertion before point	32.4 テキストの挿入
	insertion of text	32.4 テキストの挿入
	insertion type of a marker	31.5 Marker 挿入タイプ
	inside comment	35.6.3 パーサー状態
	inside string	35.6.3 パーサー状態
	`installation-directory`	40.3 オペレーティングシステムの環境
	instrumenting for Edebug	18.2.2 Edebugのためのインストルメント
	`int-to-string`	4.6 文字および文字列の変換
	`intangible (overlay property)`	39.9.2 オーバーレイのプロパティ
	`intangible (text property)`	32.19.4 特殊な意味をもつプロパティ
	integer to decimal	4.6 文字および文字列の変換
	integer to hexadecimal	4.7 文字列のフォーマット
	integer to octal	4.7 文字列のフォーマット
	integer to string	4.6 文字および文字列の変換
	integer types (C programming language)	E.9 Cの整数型
	`integer-or-marker-p`	31.2 マーカーのための述語
	`integerp`	3.3 数値のための述語
	integers	3 数値
	integers in specific radix	3.1 整数の基礎
	interaction parameters between frames	29.4.3.6 Frame Interaction Parameters
	`interactive`	21.2.1 `interactive`の使用
	interactive call	21.3 interactiveな呼び出し
	interactive code description	21.2.2 `interactive`にたいするコード文字
	interactive completion	21.2.2 `interactive`にたいするコード文字
	interactive function	21.2 コマンドの定義
	interactive spec, using	21.2.1 `interactive`の使用
	interactive specification in primitives	E.7 Emacsプリミティブの記述
	`interactive`, examples of using	21.2.3 `interactive`の使用例
	`interactive-form`	21.2.1 `interactive`の使用
	`interactive-form` property	21.2 コマンドの定義
	`interactive-form`, symbol property	21.2.1 `interactive`の使用
	`interactive-only` property	21.2 コマンドの定義
	`intern`	9.3 シンボルの作成とintern
	`intern-soft`	9.3 シンボルの作成とintern
	internal menu bar	29.3.1 Frame Layout
	internal representation of characters	33.1 テキストの表現方法
	internal tool bar	29.3.1 Frame Layout
	internal windows	28.1 Emacsウィンドウの基本概念
	`internal-border-width, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	internals, of buffer	E.8.1 バッファーの内部
	internals, of process	E.8.3 プロセスの内部
	internals, of window	E.8.2 ウィンドウの内部
	interning	9.3 シンボルの作成とintern
	interpreter	10 評価
	interpreter	10 評価
	`interpreter-mode-alist`	23.2.2 Emacsがメジャーモードを選択する方法
	`interprogram-cut-function`	32.8.5 低レベルのkillリング
	`interprogram-paste-function`	32.8.5 低レベルのkillリング
	interrupt Lisp functions	21.11 quit
	`interrupt-process`	38.8 プロセスへのシグナルの送信
	`interrupt-process-functions`	38.8 プロセスへのシグナルの送信
	intersection of sequences	6.1 シーケンス
	intervals	32.19.10 なぜテキストプロパティはインターバルではないのか
	`intervals-consed`	E.5 メモリー使用量
	invalid prefix key error	22.12 キーバインディングの変更
	`invalid-function`	10.2.4 シンボル関数インダイレクション
	`invalid-read-syntax`	2.1 プリント表現と読み取り構文
	`invalid-regexp`	34.3.1.3 正規表現内のバッククラッシュ構造
	`invert-face`	39.12.3 フェイス属性のための関数
	`invisible (overlay property)`	39.9.2 オーバーレイのプロパティ
	`invisible (text property)`	32.19.4 特殊な意味をもつプロパティ
	invisible frame	29.11 フレームの可視性
	invisible text	39.6 不可視のテキスト
	`invisible-p`	39.6 不可視のテキスト
	invisible/intangible text, and point	21.6 コマンド後のポイントの調整
	`invocation-directory`	40.3 オペレーティングシステムの環境
	`invocation-name`	40.3 オペレーティングシステムの環境
	invoking input method	21.8.4 入力メソッドの呼び出し
	invoking lisp debugger	18.1.8 デバッガの呼び出し
	is this call interactive	21.4 interactiveな呼び出しの区別
	`isnan`	3.2 浮動小数点数の基礎
	italic text	39.12.1 フェイスの属性
	`iter-close`	11.5 Generators
	`iter-defun`	11.5 Generators
	`iter-do`	11.5 Generators
	`iter-lambda`	11.5 Generators
	`iter-next`	11.5 Generators
	`iter-yield`	11.5 Generators
	`iter-yield-from`	11.5 Generators
	iteration	11.4 繰り返し
	iteration over vector or string	6.1 シーケンス

J
	`jit-lock-register`	23.6.4 Font Lockのその他の変数
	`jit-lock-unregister`	23.6.4 Font Lockのその他の変数
	joining lists	5.6.3 リストを再配置する関数
	jumbled display of bidirectional text	39.26 双方向テキストの表示
	`just-one-space`	32.7 ユーザーレベルの削除コマンド
	`justify-current-line`	32.11 fill

K
	`kbd`	22.1 キーシーケンス
	`kbd-macro-termination-hook`	21.16 キーボードマクロ
	`keep-ratio, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`kept-new-versions`	26.1.3 番号つきバックアップファイルの作成と削除
	`kept-old-versions`	26.1.3 番号つきバックアップファイルの作成と削除
	key	22.1 キーシーケンス
	key binding	22.2 キーマップの基礎
	key binding, conventions for	D.2 キーバインディングの慣習
	key lookup	22.10 キーの照合
	key sequence	22.1 キーシーケンス
	key sequence error	22.12 キーバインディングの変更
	key sequence input	21.8.1 キーシーケンス入力
	key substitution sequence	24.3 ドキュメント内でのキーバインディングの置き換え
	key translation function	22.14 イベントシーケンス変換のためのキーマップ
	`key-binding`	22.7 アクティブなキーマップ
	`key-description`	24.5 ヘルプメッセージの文字記述
	`key-translation-map`	22.14 イベントシーケンス変換のためのキーマップ
	keyboard events	21.7.1 キーボードイベント
	keyboard events in strings	21.7.15 文字列内へのキーボードイベントの配置
	keyboard events, data in	21.7.13 マウスイベントへのアクセス
	keyboard input	21.8 入力の読み取り
	keyboard input decoding on X	33.12 locale
	keyboard macro execution	21.3 interactiveな呼び出し
	keyboard macro termination	39.23 ビープ
	keyboard macro, terminating	21.8.6 その他のイベント入力の機能
	keyboard macros	21.16 キーボードマクロ
	keyboard macros (Edebug)	18.2.3 Edebugの実行モード
	`keyboard-coding-system`	33.10.8 端末I/Oのエンコーディング
	`keyboard-quit`	21.11 quit
	`keyboard-translate`	21.8.3 入力イベントの変更と変換
	`keyboard-translate-table`	21.8.3 入力イベントの変更と変換
	keymap	22 キーマップ
	`keymap (button property)`	39.19.1 ボタンのプロパティ
	`keymap (overlay property)`	39.9.2 オーバーレイのプロパティ
	`keymap (text property)`	32.19.4 特殊な意味をもつプロパティ
	keymap entry	22.10 キーの照合
	keymap format	22.3 キーマップのフォーマット
	keymap in keymap	22.10 キーの照合
	keymap inheritance	22.5 継承とキーマップ
	keymap inheritance from multiple maps	22.5 継承とキーマップ
	keymap of character	32.19.4 特殊な意味をもつプロパティ
	keymap of character (and overlays)	39.9.2 オーバーレイのプロパティ
	keymap prompt string	22.3 キーマップのフォーマット
	`keymap-parent`	22.5 継承とキーマップ
	`keymap-prompt`	22.17.1 メニューの定義
	`keymapp`	22.3 キーマップのフォーマット
	keymaps for translating events	22.14 イベントシーケンス変換のためのキーマップ
	keymaps in modes	23.2.1 メジャーモードの慣習
	keymaps, scanning	22.16 キーマップのスキャン
	keymaps, standard	Appendix G 標準的なキーマップ
	keys in documentation strings	24.3 ドキュメント内でのキーバインディングの置き換え
	keys, reserved	D.2 キーバインディングの慣習
	keystroke	22.1 キーシーケンス
	keyword symbol	12.2 変更不可な変数
	`keywordp`	12.2 変更不可な変数
	kill command repetition	21.5 コマンドループからの情報
	kill ring	32.8 killリング
	`kill-all-local-variables`	12.11.2 バッファーローカルなバインディングの作成と削除
	`kill-append`	32.8.5 低レベルのkillリング
	`kill-buffer`	27.10 バッファーのkill
	`kill-buffer-hook`	27.10 バッファーのkill
	`kill-buffer-query-functions`	27.10 バッファーのkill
	`kill-emacs`	40.2.1 Emacsのkill
	`kill-emacs-hook`	40.2.1 Emacsのkill
	`kill-emacs-query-functions`	40.2.1 Emacsのkill
	`kill-local-variable`	12.11.2 バッファーローカルなバインディングの作成と削除
	`kill-new`	32.8.5 低レベルのkillリング
	`kill-process`	38.8 プロセスへのシグナルの送信
	`kill-read-only-ok`	32.8.2 killリングのための関数
	`kill-region`	32.8.2 killリングのための関数
	`kill-ring`	32.8.6 killリングの内部
	`kill-ring-max`	32.8.6 killリングの内部
	`kill-ring-yank-pointer`	32.8.6 killリングの内部
	killing buffers	27.10 バッファーのkill
	killing Emacs	40.2.1 Emacsのkill
	`kmacro-keymap`	Appendix G 標準的なキーマップ

L
	`lambda`	13.7 無名関数
	lambda expression	13.2 ラムダ式
	`lambda` in debug	18.1.8 デバッガの呼び出し
	`lambda` in keymap	22.10 キーの照合
	lambda list	13.2.1 ラムダ式の構成要素
	lambda-list (Edebug)	18.2.15.2 仕様リスト
	`language-change` event	21.7.10 その他のシステムイベント
	largest Lisp integer	3.1 整数の基礎
	largest window	28.10 ウィンドウのサイクル順
	`last`	5.3 リスト要素へのアクセス
	`last-abbrev`	36.4 略語の照会と展開
	`last-abbrev-location`	36.4 略語の照会と展開
	`last-abbrev-text`	36.4 略語の照会と展開
	`last-buffer`	27.8 バッファーリスト
	`last-coding-system-used`	33.10.2 エンコーディングとI/O
	`last-command`	21.5 コマンドループからの情報
	`last-command-event`	21.5 コマンドループからの情報
	`last-event-frame`	21.5 コマンドループからの情報
	`last-input-event`	21.8.6 その他のイベント入力の機能
	`last-kbd-macro`	21.16 キーボードマクロ
	`last-nonmenu-event`	21.5 コマンドループからの情報
	`last-prefix-arg`	21.12 プレフィクスコマンド引数
	`last-repeatable-command`	21.5 コマンドループからの情報
	`lax-plist-get`	5.9.2 プロパティリストと外部シンボル
	`lax-plist-put`	5.9.2 プロパティリストと外部シンボル
	layout of frame	29.3.1 Frame Layout
	layout on display, and bidirectional text	39.26 双方向テキストの表示
	layout parameters of frames	29.4.3.4 レイアウトのパラメーター
	lazy loading	17.4 個別関数のダイナミックロード
	`lazy-completion-table`	20.6.1 基本的な補完関数
	`ldexp`	3.2 浮動小数点数の基礎
	least recently used window	28.10 ウィンドウのサイクル順
	left position ratio	29.4.3.2 位置のパラメーター
	`left, a frame parameter`	29.4.3.2 位置のパラメーター
	`left-fringe, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`left-fringe-width`	39.13.1 フリンジのサイズと位置
	`left-margin`	32.12 fillのマージン
	`left-margin-width`	39.16.5 マージン内への表示
	`length`	6.1 シーケンス
	`let`	12.3 ローカル変数
	`let*`	12.3 ローカル変数
	lexical binding	12.10 変数のバインディングのスコーピングルール
	lexical binding (Edebug)	18.2.9 評価
	lexical comparison of strings	4.5 文字および文字列の比較
	lexical environment	12.10.3 レキシカルバインディング
	lexical scope	12.10 変数のバインディングのスコーピングルール
	`lexical-binding`	12.10.4 レキシカルバインディングの使用
	library	16 ロード
	library compilation	17.2 バイトコンパイル関数
	library header comments	D.8 Emacsライブラリーのヘッダーの慣習
	library search	16.3 ライブラリー検索
	`libxml-parse-html-region`	32.28 HTMLとXMLの解析
	`libxml-parse-xml-region`	32.28 HTMLとXMLの解析
	line end conversion	33.10.1 コーディングシステムの基本概念
	line height	29.3.2 Frame Font
	line height	39.11 行の高さ
	line number	30.2.4 テキスト行単位の移動
	line truncation	39.3 切り詰め
	line wrapping	39.3 切り詰め
	`line-beginning-position`	30.2.4 テキスト行単位の移動
	`line-end-position`	30.2.4 テキスト行単位の移動
	`line-height (text property)`	32.19.4 特殊な意味をもつプロパティ
	`line-height (text property)`	39.11 行の高さ
	`line-move-ignore-invisible`	39.6 不可視のテキスト
	`line-number-at-pos`	30.2.4 テキスト行単位の移動
	`line-number-display-width`	39.10 表示されるテキストのサイズ
	`line-pixel-height`	39.10 表示されるテキストのサイズ
	`line-prefix`	39.3 切り詰め
	`line-spacing`	39.11 行の高さ
	`line-spacing (text property)`	32.19.4 特殊な意味をもつプロパティ
	`line-spacing (text property)`	39.11 行の高さ
	`line-spacing, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	lines	30.2.4 テキスト行単位の移動
	lines in region	30.2.4 テキスト行単位の移動
	`link, customization keyword`	15.1 一般的なキーワードアイテム
	linked list	2.3.6 コンスセルとリスト型
	linking files	25.7 ファイルの名前と属性の変更
	Lisp debugger	18.1 Lispデバッガ
	Lisp expression motion	30.2.6 バランスのとれたカッコを越えた移動
	Lisp history	1.2 Lispの歴史
	Lisp library	16 ロード
	Lisp nesting error	10.5 eval
	Lisp object	2 Lispのデータ型
	Lisp objects, stack-allocated	E.4 Stack-allocated Objects
	Lisp package	41 配布用 Lispコードの準備
	Lisp printer	19.5 出力関数
	Lisp reader	19.1 読み取りとプリントの概念
	lisp variables defined in C, restrictions	12.16 値を制限された変数
	`lisp-indent-function` property	14.6 マクロのインデント
	`lisp-mode-abbrev-table`	36.5 標準的なabbrevテーブル
	`lisp-mode.el`	23.2.9 メジャーモードの例
	`list`	5.4 コンスセルおよびリストの構築
	list all coding systems	33.10.3 Lispでのコーディングシステム
	list elements	5.3 リスト要素へのアクセス
	list form evaluation	10.2.3 リストフォームの分類
	list in keymap	22.10 キーの照合
	list length	6.1 シーケンス
	list modification	5.5 リスト変数の変更
	list motion	30.2.6 バランスのとれたカッコを越えた移動
	list predicates	5.2 リストのための述語
	list reverse	6.1 シーケンス
	list structure	2.3.6 コンスセルとリスト型
	list structure	5.1 リストとコンスセル
	list to vector	6.1 シーケンス
	list, replace element	5.6.1 `setcar`によるリスト要素の変更
	`list-buffers-directory`	27.4 バッファーのファイル名
	`list-charset-chars`	33.7 文字セット
	`list-fonts`	39.12.12 低レベルのフォント表現
	`list-load-path-shadows`	16.3 ライブラリー検索
	`list-processes`	38.6 プロセスの情報
	`list-system-processes`	38.12 別のプセスへのアクセス
	`list-timers`	40.11 遅延実行のためのタイマー
	`listify-key-sequence`	21.8.6 その他のイベント入力の機能
	listing all buffers	27.8 バッファーリスト
	`listp`	5.2 リストのための述語
	lists	5 リスト
	lists and cons cells	5.1 リストとコンスセル
	lists as sets	5.7 集合としてのリストの使用
	literal evaluation	10.2.1 自己評価を行うフォーム
	literate programming	32.17.2 メジャーモードが制御するインデント
	little endian	38.20.1 データレイアウトの記述
	live buffer	27.10 バッファーのkill
	live windows	28.1 Emacsウィンドウの基本概念
	`ln`	25.7 ファイルの名前と属性の変更
	`load`	16.1 プログラムがロードを行う方法
	load error with require	16.7 名前つき機能
	load errors	16.1 プログラムがロードを行う方法
	`load, customization keyword`	15.1 一般的なキーワードアイテム
	`load-average`	40.3 オペレーティングシステムの環境
	`load-file`	16.1 プログラムがロードを行う方法
	`load-file-name`	16.1 プログラムがロードを行う方法
	`load-file-rep-suffixes`	16.2 ロードでの拡張子
	`load-history`	16.8 どのファイルで特定のシンボルが定義されているか
	`load-in-progress`	16.1 プログラムがロードを行う方法
	`load-library`	16.1 プログラムがロードを行う方法
	`load-path`	16.3 ライブラリー検索
	`load-prefer-newer`	16.2 ロードでの拡張子
	`load-read-function`	16.1 プログラムがロードを行う方法
	`load-suffixes`	16.2 ロードでの拡張子
	`load-theme`	15.6 カスタムテーマ
	loading	16 ロード
	loading hooks	16.10 ロードのためのフック
	loading, and non-ASCII characters	16.4 非ASCII文字のロード
	`loadup.el`	E.1 Emacsのビルド
	local binding	12.3 ローカル変数
	local keymap	22.7 アクティブなキーマップ
	local variables	12.3 ローカル変数
	local variables, killed by major mode	12.11.2 バッファーローカルなバインディングの作成と削除
	`local-abbrev-table`	36.5 標準的なabbrevテーブル
	`local-function-key-map`	22.14 イベントシーケンス変換のためのキーマップ
	`local-key-binding`	22.11 キー照合のための関数
	`local-map (overlay property)`	39.9.2 オーバーレイのプロパティ
	`local-map (text property)`	32.19.4 特殊な意味をもつプロパティ
	`local-set-key`	22.15 キーのバインドのためのコマンド
	`local-unset-key`	22.15 キーのバインドのためのコマンド
	`local-variable-if-set-p`	12.11.2 バッファーローカルなバインディングの作成と削除
	`local-variable-p`	12.11.2 バッファーローカルなバインディングの作成と削除
	locale	33.12 locale
	`locale-coding-system`	33.12 locale
	locale-dependent string comparison	4.5 文字および文字列の比較
	locale-dependent string equivalence	4.5 文字および文字列の比較
	`locale-info`	33.12 locale
	locate file in path	25.6.6 標準的な場所へのファイルの配置
	`locate-file`	25.6.6 標準的な場所へのファイルの配置
	`locate-library`	16.3 ライブラリー検索
	`locate-user-emacs-file`	25.9.7 標準的なファイル名
	lock file	25.5 ファイルのロック
	`lock-buffer`	25.5 ファイルのロック
	`log`	3.9 標準的な数学関数
	`logand`	3.8 ビット演算 on Integers
	`logb`	3.2 浮動小数点数の基礎
	logging echo-area messages	39.4.3 `Messages`へのメッセージのロギング
	logical arithmetic	3.8 ビット演算 on Integers
	logical order	39.26 双方向テキストの表示
	logical shift	3.8 ビット演算 on Integers
	`logior`	3.8 ビット演算 on Integers
	`lognot`	3.8 ビット演算 on Integers
	`logxor`	3.8 ビット演算 on Integers
	looking up abbrevs	36.4 略語の照会と展開
	looking up fonts	39.12.10 フォントの照会
	`looking-at`	34.4 正規表現の検索
	`looking-at-p`	34.4 正規表現の検索
	`looking-back`	34.4 正規表現の検索
	lookup tables	8 ハッシュテーブル
	`lookup-key`	22.11 キー照合のための関数
	loops, infinite	18.1.2 無限ループのデバッグ
	lower case	4.8 Lispでの大文字小文字変換
	`lower-frame`	29.12 Raising, Lowering and Restacking Frames
	lowering a frame	29.12 Raising, Lowering and Restacking Frames
	LRO	39.26 双方向テキストの表示
	`lsh`	3.8 ビット演算 on Integers
	`lwarn`	39.5.1 警告の基礎

M
	`M-g`	22.6 プレフィクスキー
	`M-o`	22.6 プレフィクスキー
	`M-s`	22.6 プレフィクスキー
	`M-x`	21.3 interactiveな呼び出し
	Maclisp	1.2 Lispの歴史
	macro	13.1 関数とは?
	macro argument evaluation	14.5.2 マクロ引数の多重評価
	macro call	14.2 マクロ呼び出しの展開
	macro call evaluation	10.2.6 Lispマクロの評価
	macro caveats	14.5 マクロ使用に関する一般的な問題
	macro compilation	17.2 バイトコンパイル関数
	macro descriptions	1.3.7.1 関数の説明例
	macro expansion	14.2 マクロ呼び出しの展開
	macro, how to define	14.4 マクロの定義
	`macroexpand`	14.2 マクロ呼び出しの展開
	`macroexpand-1`	14.2 マクロ呼び出しの展開
	`macroexpand-all`	14.2 マクロ呼び出しの展開
	`macrop`	14.1 単純なマクロの例
	macros	14 マクロ
	macros, at compile time	17.5 コンパイル中の評価
	magic autoload comment	16.5 autoload
	magic file names	25.12 特定のファイル名の“Magic”の作成
	`magic-fallback-mode-alist`	23.2.2 Emacsがメジャーモードを選択する方法
	`magic-mode-alist`	23.2.2 Emacsがメジャーモードを選択する方法
	`mail-host-address`	40.3 オペレーティングシステムの環境
	main window	28.19 Side Windows
	main window of a frame	28.19 Side Windows
	major mode	23.2 メジャーモード
	major mode command	23.2 メジャーモード
	major mode conventions	23.2.1 メジャーモードの慣習
	major mode hook	23.2.1 メジャーモードの慣習
	major mode keymap	22.7 アクティブなキーマップ
	major mode, automatic selection	23.2.2 Emacsがメジャーモードを選択する方法
	`major-mode`	23.2 メジャーモード
	`make-abbrev-table`	36.1 abbrevテーブル
	`make-auto-save-file-name`	26.2 自動保存
	`make-backup-file-name`	26.1.4 バックアップファイルの命名
	`make-backup-file-name-function`	26.1.1 バックアップファイルの作成
	`make-backup-files`	26.1.1 バックアップファイルの作成
	`make-bool-vector`	6.7 ブールベクター
	`make-button`	39.19.3 ボタンの作成
	`make-byte-code`	17.7 バイトコード関数オブジェクト
	`make-category-set`	35.8 カテゴリー
	`make-category-table`	35.8 カテゴリー
	`make-char-table`	6.6 文字テーブル
	`make-composed-keymap`	22.5 継承とキーマップ
	`make-condition-variable`	37.3 Condition Variables
	`make-directory`	25.11 ディレクトリーの作成・コピー・削除
	`make-display-table`	39.22.2 ディスプレーテーブル
	`make-finalizer`	2.3.20 Finalizer Type
	`make-frame`	29.1 フレームの作成
	`make-frame-invisible`	29.11 フレームの可視性
	`make-frame-on-display`	29.2 複数の端末
	`make-frame-visible`	29.11 フレームの可視性
	`make-frame-visible` event	21.7.10 その他のシステムイベント
	`make-glyph-code`	39.22.4 グリフ
	`make-hash-table`	8.1 ハッシュテーブルの作成
	`make-help-screen`	24.6 ヘルプ関数
	`make-indirect-buffer`	27.11 インダイレクトバッファー
	`make-keymap`	22.4 キーマップの作成
	`make-list`	5.4 コンスセルおよびリストの構築
	`make-local-variable`	12.11.2 バッファーローカルなバインディングの作成と削除
	`make-marker`	31.3 マーカーを作成する関数
	`make-mutex`	37.2 Mutexes
	`make-nearby-temp-file`	25.9.5 一意なファイル名の生成
	`make-network-process`	38.17.1 `make-network-process`
	`make-obsolete`	13.12 関数を陳腐と宣言する
	`make-obsolete-variable`	12.15 変数のエイリアス
	`make-overlay`	39.9.1 オーバーレイの管理
	`make-pipe-process`	38.4 非同期プロセスの作成
	`make-process`	38.4 非同期プロセスの作成
	`make-progress-reporter`	39.4.2 処理の進捗レポート
	`make-record`	7.1 Record Functions
	`make-ring`	6.8 オブジェクト用固定長リングの管理
	`make-serial-process`	38.19 シリアルポートとの対話
	`make-sparse-keymap`	22.4 キーマップの作成
	`make-string`	4.3 文字列の作成
	`make-symbol`	9.3 シンボルの作成とintern
	`make-symbolic-link`	25.7 ファイルの名前と属性の変更
	`make-syntax-table`	35.3 構文テーブルの関数
	`make-temp-file`	25.9.5 一意なファイル名の生成
	`make-temp-name`	25.9.5 一意なファイル名の生成
	`make-text-button`	39.19.3 ボタンの作成
	`make-thread`	37.1 Basic Thread Functions
	`make-translation-table`	33.9 文字の変換
	`make-translation-table-from-alist`	33.9 文字の変換
	`make-translation-table-from-vector`	33.9 文字の変換
	`make-variable-buffer-local`	12.11.2 バッファーローカルなバインディングの作成と削除
	`make-vector`	6.5 ベクターのための関数
	`make-xwidget`	39.18 Embedded Native Widgets
	making backup files	26.1.1 バックアップファイルの作成
	making buttons	39.19.3 ボタンの作成
	`makunbound`	12.4 When a Variable is Void
	malicious use of directional overrides	39.26 双方向テキストの表示
	managing overlays	39.9.1 オーバーレイの管理
	manipulating buttons	39.19.4 ボタンの操作
	`map-char-table`	6.6 文字テーブル
	`map-charset-chars`	33.7 文字セット
	`map-keymap`	22.16 キーマップのスキャン
	`map-y-or-n-p`	20.8 複数のY-or-Nの問い合わせ
	`mapatoms`	9.3 シンボルの作成とintern
	`mapbacktrace`	18.1.9 デバッガの内部
	`mapc`	13.6 関数のマッピング
	`mapcan`	13.6 関数のマッピング
	`mapcar`	13.6 関数のマッピング
	`mapconcat`	13.6 関数のマッピング
	`maphash`	8.2 ハッシュテーブルへのアクセス
	mapped frame	29.11 フレームの可視性
	mapping functions	13.6 関数のマッピング
	margins, display	39.16.5 マージン内への表示
	margins, filling	32.12 fillのマージン
	`mark`	31.7 マーク
	mark excursion	30.3 エクスカーション
	mark ring	31.7 マーク
	mark, the	31.7 マーク
	`mark-active`	31.7 マーク
	`mark-even-if-inactive`	31.7 マーク
	`mark-marker`	31.7 マーク
	`mark-ring`	31.7 マーク
	`mark-ring-max`	31.7 マーク
	marker argument	21.2.2 `interactive`にたいするコード文字
	marker creation	31.3 マーカーを作成する関数
	marker garbage collection	31.1 マーカーの概要
	marker information	31.4 マーカーからの情報
	marker input stream	19.2 入力ストリーム
	marker output stream	19.4 出力ストリーム
	marker relocation	31.1 マーカーの概要
	marker, how to move position	31.6 マーカー位置の移動
	`marker-buffer`	31.4 マーカーからの情報
	`marker-insertion-type`	31.5 Marker 挿入タイプ
	`marker-position`	31.4 マーカーからの情報
	`markerp`	31.2 マーカーのための述語
	markers	31 マーカー
	markers as numbers	31.1 マーカーの概要
	markers, predicates for	31.2 マーカーのための述語
	match data	34.6 マッチデータ
	`match, customization keyword`	15.4.4 型キーワード
	`match-alternatives, customization keyword`	15.4.2 複合型
	`match-beginning`	34.6.2 単純なマッチデータへのアクセス
	`match-data`	34.6.3 マッチデータ全体へのアクセス
	`match-end`	34.6.2 単純なマッチデータへのアクセス
	`match-string`	34.6.2 単純なマッチデータへのアクセス
	`match-string-no-properties`	34.6.2 単純なマッチデータへのアクセス
	`match-substitute-replacement`	34.6.1 マッチしたテキストの置換
	mathematical functions	3.9 標準的な数学関数
	`max`	3.4 数値の比較
	`max-char`	33.5 文字コード
	`max-image-size`	39.17.9 イメージの表示
	`max-lisp-eval-depth`	10.5 eval
	`max-mini-window-height`	20.11 ミニバッファーのウィンドウ
	`max-specpdl-size`	12.3 ローカル変数
	`maximize-window`	28.4 ウィンドウのリサイズ
	maximized frames	29.4.3.3 サイズのパラメーター
	maximizing windows	28.4 ウィンドウのリサイズ
	maximum Lisp integer	3.1 整数の基礎
	maximum value of character codepoint	33.5 文字コード
	maximum value of sequence	6.1 シーケンス
	`maximum-scroll-margin`	28.23 テキスト的なスクロール
	`maybe_quit`, use in Lisp primitives	E.7 Emacsプリミティブの記述
	`md5`	32.26 チェックサムとハッシュ
	MD5 checksum	32.26 チェックサムとハッシュ
	MD5 checksum	32.27 GnuTLS Cryptography
	measuring resource usage	18.5 プロファイリング
	`member`	5.7 集合としてのリストの使用
	`member-ignore-case`	5.7 集合としてのリストの使用
	membership in a list	5.7 集合としてのリストの使用
	memory allocation	E.3 ガーベージコレクション
	memory usage	18.5 プロファイリング
	memory usage	E.5 メモリー使用量
	`memory-full`	E.3 ガーベージコレクション
	`memory-info`	E.3 ガーベージコレクション
	`memory-limit`	E.3 ガーベージコレクション
	`memory-use-counts`	E.3 ガーベージコレクション
	`memq`	5.7 集合としてのリストの使用
	`memql`	5.7 集合としてのリストの使用
	menu bar	22.17.5 メニューバー Bar
	menu bar keymaps	Appendix G 標準的なキーマップ
	menu definition example	22.17.4 メニューの例
	menu item	22.17.1 メニューの定義
	menu keymaps	22.17 メニューキーアップ
	menu modification	22.17.7 メニューの変更
	menu prompt string	22.17.1 メニューの定義
	menu separators	22.17.1.3 メニューセパレーター
	`menu-bar` prefix key	21.8.1 キーシーケンス入力
	`menu-bar-file-menu`	Appendix G 標準的なキーマップ
	`menu-bar-final-items`	22.17.5 メニューバー Bar
	`menu-bar-help-menu`	Appendix G 標準的なキーマップ
	`menu-bar-lines, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`menu-bar-options-menu`	Appendix G 標準的なキーマップ
	`menu-bar-tools-menu`	Appendix G 標準的なキーマップ
	`menu-bar-update-hook`	22.17.5 メニューバー Bar
	`menu-item`	22.17.1.2 拡張メニューアイテム
	`menu-prompt-more-char`	22.17.3 メニューとキーボード
	menus, popup	29.17 ポップアップメニュー
	`merge-face-attribute`	39.12.3 フェイス属性のための関数
	`message`	39.4.1 エコーエリアへのメッセージの表示
	message digest	32.26 チェックサムとハッシュ
	message, finding what causes a particular message	18.1.1 エラーによるデバッガへのエンター
	`message-box`	39.4.1 エコーエリアへのメッセージの表示
	`message-log-max`	39.4.3 `Messages`へのメッセージのロギング
	`message-or-box`	39.4.1 エコーエリアへのメッセージの表示
	`message-truncate-lines`	39.4.4 エコーエリアのカスタマイズ
	`messages-buffer`	39.4.3 `Messages`へのメッセージのロギング
	meta character key constants	22.12 キーバインディングの変更
	meta character printing	24.5 ヘルプメッセージの文字記述
	meta characters	2.3.3.4 メタ文字構文
	meta characters lookup	22.3 キーマップのフォーマット
	`meta-prefix-char`	22.11 キー照合のための関数
	`min`	3.4 数値の比較
	`min-height, a frame parameter`	29.4.3.3 サイズのパラメーター
	`min-margins, a window parameter`	28.29 ウィンドウのパラメーター
	`min-width, a frame parameter`	29.4.3.3 サイズのパラメーター
	minibuffer	20 ミニバッファー
	minibuffer completion	20.6.2 補完とミニバッファー
	minibuffer contents, accessing	20.12 ミニバッファーのコンテンツ
	minibuffer history	20.4 ミニバッファーのヒストリー
	minibuffer input	21.13 再帰編集
	minibuffer input, and command-line arguments	38.2 shell引数
	minibuffer input, reading lisp objects	20.3 ミニバッファーでのLispオブジェクトの読み取り
	minibuffer input, reading text strings	20.2 ミニバッファーでのテキスト文字列の読み取り
	minibuffer window, and `next-window`	28.10 ウィンドウのサイクル順
	minibuffer windows	20.11 ミニバッファーのウィンドウ
	`minibuffer, a frame parameter`	29.4.3.5 バッファーのパラメーター
	`minibuffer-allow-text-properties`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`minibuffer-auto-raise`	29.12 Raising, Lowering and Restacking Frames
	`minibuffer-complete`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-complete-and-exit`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-complete-word`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-completion-confirm`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-completion-help`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-completion-predicate`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-completion-table`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-confirm-exit-commands`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-contents`	20.12 ミニバッファーのコンテンツ
	`minibuffer-contents-no-properties`	20.12 ミニバッファーのコンテンツ
	`minibuffer-depth`	20.13 再帰的なミニバッファー
	`minibuffer-exit, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`minibuffer-exit-hook`	20.14 ミニバッファー、その他の事項
	`minibuffer-frame-alist`	29.4.2 フレームの初期パラメーター
	`minibuffer-help-form`	20.14 ミニバッファー、その他の事項
	`minibuffer-history`	20.4 ミニバッファーのヒストリー
	`minibuffer-inactive-mode`	20.14 ミニバッファー、その他の事項
	minibuffer-less frame	29.3.1 Frame Layout
	`minibuffer-local-completion-map`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-local-filename-completion-map`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-local-map`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`minibuffer-local-must-match-map`	20.6.3 補完を行うミニバッファーコマンド
	`minibuffer-local-ns-map`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`minibuffer-local-shell-command-map`	20.6.5 ファイル名の読み取り
	`minibuffer-message`	20.14 ミニバッファー、その他の事項
	`minibuffer-message-timeout`	20.14 ミニバッファー、その他の事項
	minibuffer-only frame	29.3.1 Frame Layout
	minibuffer-only frame	29.4.2 フレームの初期パラメーター
	`minibuffer-prompt`	20.12 ミニバッファーのコンテンツ
	`minibuffer-prompt-end`	20.12 ミニバッファーのコンテンツ
	`minibuffer-prompt-properties`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`minibuffer-prompt-width`	20.12 ミニバッファーのコンテンツ
	`minibuffer-scroll-window`	20.14 ミニバッファー、その他の事項
	`minibuffer-selected-window`	20.14 ミニバッファー、その他の事項
	`minibuffer-setup-hook`	20.14 ミニバッファー、その他の事項
	`minibuffer-window`	20.11 ミニバッファーのウィンドウ
	`minibuffer-window-active-p`	20.11 ミニバッファーのウィンドウ
	`minibuffer-with-setup-hook`	20.14 ミニバッファー、その他の事項
	`minibufferp`	20.14 ミニバッファー、その他の事項
	`minimize-window`	28.4 ウィンドウのリサイズ
	minimized frame	29.11 フレームの可視性
	minimizing windows	28.4 ウィンドウのリサイズ
	minimum Lisp integer	3.1 整数の基礎
	minimum value of sequence	6.1 シーケンス
	minor mode	23.3 マイナーモード
	minor mode conventions	23.3.1 マイナーモード記述の規約
	`minor-mode-alist`	23.4.4 モードラインで使用される変数
	`minor-mode-key-binding`	22.11 キー照合のための関数
	`minor-mode-list`	23.3 マイナーモード
	`minor-mode-map-alist`	22.9 アクティブなキーマップの制御
	`minor-mode-overriding-map-alist`	22.9 アクティブなキーマップの制御
	mirroring of characters	33.6 文字のプロパティ
	`misc-objects-consed`	E.5 メモリー使用量
	`mkdir`	25.11 ディレクトリーの作成・コピー・削除
	`mod`	3.6 算術演算
	mode	23 メジャーモードとマイナーモード
	mode bits	25.6.1 アクセシビリティのテスト
	mode help	23.2.3 メジャーモードでのヘルプ入手
	mode hook	23.2.1 メジャーモードの慣習
	mode line	23.4 モードラインのフォーマット
	mode line construct	23.4.2 モードラインのデータ構造
	mode loading	23.2.1 メジャーモードの慣習
	mode variable	23.3.1 マイナーモード記述の規約
	`mode-class (property)`	23.2.1 メジャーモードの慣習
	`mode-line` prefix key	21.8.1 キーシーケンス入力
	`mode-line-buffer-identification`	23.4.4 モードラインで使用される変数
	`mode-line-client`	23.4.4 モードラインで使用される変数
	`mode-line-coding-system-map`	Appendix G 標準的なキーマップ
	`mode-line-column-line-number-mode-map`	Appendix G 標準的なキーマップ
	`mode-line-end-spaces`	23.4.4 モードラインで使用される変数
	`mode-line-format`	23.4.3 モードライン制御のトップレベル
	`mode-line-format, a window parameter`	28.29 ウィンドウのパラメーター
	`mode-line-frame-identification`	23.4.4 モードラインで使用される変数
	`mode-line-front-space`	23.4.4 モードラインで使用される変数
	`mode-line-input-method-map`	Appendix G 標準的なキーマップ
	`mode-line-misc-info`	23.4.4 モードラインで使用される変数
	`mode-line-modes`	23.4.4 モードラインで使用される変数
	`mode-line-modified`	23.4.4 モードラインで使用される変数
	`mode-line-mule-info`	23.4.4 モードラインで使用される変数
	`mode-line-percent-position`	23.4.4 モードラインで使用される変数
	`mode-line-position`	23.4.4 モードラインで使用される変数
	`mode-line-process`	23.4.4 モードラインで使用される変数
	`mode-line-remote`	23.4.4 モードラインで使用される変数
	`mode-name`	23.4.4 モードラインで使用される変数
	`mode-specific-map`	22.6 プレフィクスキー
	model/view/controller	39.20 抽象的なディスプレー
	modification flag (of buffer)	27.5 バッファーの変更
	modification of lists	5.6.3 リストを再配置する関数
	modification time of buffer	27.6 バッファーの変更 Time
	modification time of file	25.6.4 ファイルの属性
	`modification-hooks (overlay property)`	39.9.2 オーバーレイのプロパティ
	`modification-hooks (text property)`	32.19.4 特殊な意味をもつプロパティ
	modifier bits (of input character)	21.7.1 キーボードイベント
	modifiers of events	21.8.3 入力イベントの変更と変換
	modify a list	5.5 リスト変数の変更
	`modify-all-frames-parameters`	29.4.1 フレームパラメーターへのアクセス
	`modify-category-entry`	35.8 カテゴリー
	`modify-frame-parameters`	29.4.1 フレームパラメーターへのアクセス
	`modify-syntax-entry`	35.3 構文テーブルの関数
	modifying strings	4.4 文字列の変更
	`module-file-suffix`	16.11 Emacs Dynamic Modules
	modulus	3.6 算術演算
	`momentary-string-display`	39.8 一時的な表示
	most recently selected windows	28.9 ウィンドウの選択
	most recently used window	28.10 ウィンドウのサイクル順
	`most-negative-fixnum`	3.1 整数の基礎
	`most-positive-fixnum`	3.1 整数の基礎
	motion based on parsing	35.6.1 パースにもとづくモーションコマンド
	motion by chars, words, lines, lists	30.2 モーション
	motion event	21.7.8 モーションイベント
	mouse click event	21.7.4 クリックイベント
	mouse drag event	21.7.5 ドラッグイベント
	mouse dragging parameters	29.4.3.7 Mouse Dragging Parameters
	mouse events, data in	21.7.13 マウスイベントへのアクセス
	mouse events, in special parts of frame	21.8.1 キーシーケンス入力
	mouse events, repeated	21.7.7 リピートイベント
	mouse motion events	21.7.8 モーションイベント
	mouse pointer shape	29.19 ポインターの形状
	mouse position	29.16 マウスの位置
	mouse position list	21.7.4 クリックイベント
	mouse position list, accessing	21.7.13 マウスイベントへのアクセス
	mouse tracking	29.15 マウスの追跡
	mouse, availability	29.25 ディスプレー機能のテスト
	mouse-1	32.19.8 クリック可能なテキストの定義
	`mouse-1-click-follows-link`	32.19.8 クリック可能なテキストの定義
	mouse-2	D.2 キーバインディングの慣習
	`mouse-absolute-pixel-position`	29.16 マウスの位置
	`mouse-action (button property)`	39.19.1 ボタンのプロパティ
	`mouse-appearance-menu-map`	Appendix G 標準的なキーマップ
	`mouse-autoselect-window`	28.27 Mouse Window Auto-selection
	`mouse-color, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`mouse-face (button property)`	39.19.1 ボタンのプロパティ
	`mouse-face (overlay property)`	39.9.2 オーバーレイのプロパティ
	`mouse-face (text property)`	32.19.4 特殊な意味をもつプロパティ
	`mouse-leave-buffer-hook`	Appendix H 標準的なフック
	`mouse-movement-p`	21.7.12 イベントの分類
	`mouse-on-link-p`	32.19.8 クリック可能なテキストの定義
	`mouse-pixel-position`	29.16 マウスの位置
	`mouse-position`	29.16 マウスの位置
	`mouse-position-function`	29.16 マウスの位置
	`mouse-wheel-down-event`	21.7.10 その他のシステムイベント
	`mouse-wheel-frame, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`mouse-wheel-up-event`	21.7.10 その他のシステムイベント
	move to beginning or end of buffer	30.2.3 バッファー終端への移動
	`move-frame-functions`	29.3.3 Frame Position
	`move-marker`	31.6 マーカー位置の移動
	`move-overlay`	39.9.1 オーバーレイの管理
	`move-point-visually`	39.26 双方向テキストの表示
	`move-to-column`	32.16 列を数える
	`move-to-left-margin`	32.12 fillのマージン
	`move-to-window-group-line`	30.2.5 スクリーン行単位の移動
	`move-to-window-group-line-function`	30.2.5 スクリーン行単位の移動
	`move-to-window-line`	30.2.5 スクリーン行単位の移動
	`movemail`	38.1 サブプロセスを作成する関数
	moving across syntax classes	35.5 モーションと構文
	moving markers	31.6 マーカー位置の移動
	MS-DOS and file modes	25.6.1 アクセシビリティのテスト
	MS-Windows file-name syntax	25.9 ファイルの名前
	`mule-keymap`	22.6 プレフィクスキー
	multi-file package	41.3 複数ファイルのパッケージ
	multi-frame images	39.17.10 マルチフレームのイメージ
	multi-mode indentation	32.17.2 メジャーモードが制御するインデント
	multi-monitor	29.2 複数の端末
	`multi-query-replace-map`	34.7 検索と置換
	multi-tty	29.2 複数の端末
	multibyte characters	33 非ASCII文字
	multibyte text	33.1 テキストの表現方法
	`multibyte-char-to-unibyte`	33.3 テキスト表現の変換
	`multibyte-string-p`	33.1 テキストの表現方法
	`multibyte-syntax-as-symbol`	35.6.5 パースを制御するためのパラメーター
	multiline font lock	23.6.9 複数行のFont Lock構造
	multiple terminals	29.2 複数の端末
	multiple windows	28.1 Emacsウィンドウの基本概念
	multiple X displays	29.2 複数の端末
	multiple yes-or-no questions	20.8 複数のY-or-Nの問い合わせ
	multiple-dispatch methods	13.8 Generic Functions
	`multiple-frames`	29.6 フレームのタイトル
	`mutex-lock`	37.2 Mutexes
	`mutex-name`	37.2 Mutexes
	`mutex-unlock`	37.2 Mutexes
	`mutexp`	37.2 Mutexes

N
	`name, a frame parameter`	29.4.3.1 基本パラメーター
	named function	13.3 関数の命名
	naming backup files	26.1.4 バックアップファイルの命名
	NaN	3.2 浮動小数点数の基礎
	`narrow-map`	Appendix G 標準的なキーマップ
	`narrow-to-page`	30.4 ナローイング
	`narrow-to-region`	30.4 ナローイング
	narrowing	30.4 ナローイング
	native edges	29.3.1 Frame Layout
	native frame	29.3.1 Frame Layout
	native height	29.3.1 Frame Layout
	native position	29.3.1 Frame Layout
	native size	29.3.1 Frame Layout
	native width	29.3.1 Frame Layout
	`natnump`	3.3 数値のための述語
	natural numbers	3.3 数値のための述語
	`nbutlast`	5.3 リスト要素へのアクセス
	`nconc`	5.6.3 リストを再配置する関数
	negative infinity	3.2 浮動小数点数の基礎
	`negative-argument`	21.12 プレフィクスコマンド引数
	nest frame	29.14 Child Frames
	network byte ordering	38.20.1 データレイアウトの記述
	network connection	38.14 ネットワーク接続
	network connection, encrypted	38.14 ネットワーク接続
	network servers	38.15 ネットワークサーバー
	network service name, and default coding system	33.10.5 デフォルトのコーディングシステム
	`network-coding-system-alist`	33.10.5 デフォルトのコーディングシステム
	`network-interface-info`	38.18 その他のネットワーク機能
	`network-interface-list`	38.18 その他のネットワーク機能
	new file message	25.1.2 visitのためのサブルーチン
	newline	2.3.3.1 基本的な文字構文
	`newline`	32.5 ユーザーレベルの挿入コマンド
	newline and Auto Fill mode	32.5 ユーザーレベルの挿入コマンド
	newline in print	19.5 出力関数
	newline in strings	2.3.8.1 文字列の構文
	`newline-and-indent`	32.17.2 メジャーモードが制御するインデント
	next input	21.8.6 その他のイベント入力の機能
	`next-button`	39.19.5 ボタンのためのバッファーコマンド
	`next-char-property-change`	32.19.3 テキストプロパティの検索関数
	`next-complete-history-element`	20.10 ミニバッファーのコマンド
	`next-frame`	29.8 すべてのフレームを探す
	`next-history-element`	20.10 ミニバッファーのコマンド
	`next-matching-history-element`	20.10 ミニバッファーのコマンド
	`next-overlay-change`	39.9.3 オーバーレイにたいする検索
	`next-property-change`	32.19.3 テキストプロパティの検索関数
	`next-screen-context-lines`	28.23 テキスト的なスクロール
	`next-single-char-property-change`	32.19.3 テキストプロパティの検索関数
	`next-single-property-change`	32.19.3 テキストプロパティの検索関数
	`next-window`	28.10 ウィンドウのサイクル順
	`nil`	1.3.2 `nil`と`t`
	`nil` as a list	2.3.6.1 ボックスダイアグラムとしてのリストの描写
	`nil` in keymap	22.10 キーの照合
	`nil` input stream	19.2 入力ストリーム
	`nil` output stream	19.4 出力ストリーム
	`nlistp`	5.2 リストのための述語
	`no-accept-focus, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`no-byte-compile`	17 バイトコンパイル
	`no-catch`	11.6.1 明示的な非ローカル脱出: `catch`と`throw`
	`no-conversion coding system`	33.10.1 コーディングシステムの基本概念
	`no-delete-other-windows, a window parameter`	28.29 ウィンドウのパラメーター
	`no-focus-on-map, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`no-other-frame, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	`no-other-window, a window parameter`	28.29 ウィンドウのパラメーター
	`no-redraw-on-reenter`	39.1 スクリーンのリフレッシュ
	`no-self-insert` property	36.2 abbrevの定義
	`no-special-glyphs, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	node, ewoc	39.20 抽象的なディスプレー
	non-ASCII characters	33 非ASCII文字
	non-ASCII characters in loaded files	16.4 非ASCII文字のロード
	non-ASCII text in keybindings	22.15 キーのバインドのためのコマンド
	non-capturing group	34.3.1.3 正規表現内のバッククラッシュ構造
	non-greedy repetition characters in regexp	34.3.1.1 正規表現内の特殊文字
	nondirectory part (of file name)	25.9.1 ファイル名の構成要素
	`noninteractive`	40.17 batchモード
	nonlocal exits	11.6 非ローカル脱出
	nonlocal exits, cleaning up	11.6.4 非ローカル脱出のクリーンアップ
	nonprinting characters, reading	21.8.5 クォートされた文字の入力
	`noreturn`	18.4 カバレッジテスト
	normal hook	23.1 フック
	`normal-auto-fill-function`	32.14 オートfill
	`normal-backup-enable-predicate`	26.1.1 バックアップファイルの作成
	`normal-mode`	23.2.2 Emacsがメジャーモードを選択する方法
	`not`	11.3 条件の組み合わせ
	`not-modified`	27.5 バッファーの変更
	notation	1.3.3 評価の表記
	notifications, on desktop	40.19 デスクトップ通知
	`notifications-close-notification`	40.19 デスクトップ通知
	`notifications-get-capabilities`	40.19 デスクトップ通知
	`notifications-get-server-information`	40.19 デスクトップ通知
	`notifications-notify`	40.19 デスクトップ通知
	`nreverse`	6.1 シーケンス
	`ns-appearance, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`ns-transparent-titlebar, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`nth`	5.3 リスト要素へのアクセス
	`nthcdr`	5.3 リスト要素へのアクセス
	`null`	5.2 リストのための述語
	null bytes, and decoding text	33.10.3 Lispでのコーディングシステム
	`num-input-keys`	21.8.1 キーシーケンス入力
	`num-nonmacro-input-events`	21.8.2 単一イベントの読み取り
	number comparison	3.4 数値の比較
	number conversions	3.5 数値の変換
	`number-or-marker-p`	31.2 マーカーのための述語
	`number-sequence`	5.4 コンスセルおよびリストの構築
	`number-to-string`	4.6 文字および文字列の変換
	numbered backups	26.1.3 番号つきバックアップファイルの作成と削除
	`numberp`	3.3 数値のための述語
	numbers	3 数値
	numeric prefix argument	21.12 プレフィクスコマンド引数
	numeric prefix argument usage	21.2.2 `interactive`にたいするコード文字
	numerical RGB color specification	29.22 カラー名

O
	`obarray`	9.3 シンボルの作成とintern
	obarray	9.3 シンボルの作成とintern
	obarray in completion	20.6.1 基本的な補完関数
	object	2 Lispのデータ型
	object internals	E.8 オブジェクトの内部
	object to string	19.5 出力関数
	obsolete functions	13.12 関数を陳腐と宣言する
	octal character code	2.3.3.2 一般的なエスケープ構文
	octal character input	21.8.5 クォートされた文字の入力
	octal escapes	39.22.1 通常の表示の慣習
	octal numbers	3.1 整数の基礎
	old advices, porting	13.11.4 古いdefadviceを使用するコードの改良
	`one-window-p`	28.10 ウィンドウのサイクル順
	`only-global-abbrevs`	36.2 abbrevの定義
	opacity, frame	29.4.3.10 フォントとカラーのパラメーター
	`open-dribble-file`	40.13.2 入力の記録
	`open-network-stream`	38.14 ネットワーク接続
	`open-paren-in-column-0-is-defun-start`	30.2.6 バランスのとれたカッコを越えた移動
	`open-termscript`	40.14 端末の出力
	OpenType font	39.12.12 低レベルのフォント表現
	operating system environment	40.3 オペレーティングシステムの環境
	operating system signal	40.2.1 Emacsのkill
	`operations (property)`	25.12 特定のファイル名の“Magic”の作成
	optimize regexp	34.3.3 正規表現の関数
	option descriptions	1.3.7.2 変数の説明例
	optional arguments	13.2.3 引数リストのその他機能
	options on command line	40.1.4 コマンドライン引数
	`options, defcustom keyword`	15.3 カスタマイズ変数の定義
	`or`	11.3 条件の組み合わせ
	ordering of windows, cyclic	28.10 ウィンドウのサイクル順
	origin of display	29.3.1 Frame Layout
	`other-buffer`	27.8 バッファーリスト
	`other-window`	28.10 ウィンドウのサイクル順
	`other-window, a window parameter`	28.29 ウィンドウのパラメーター
	`other-window-scroll-buffer`	28.23 テキスト的なスクロール
	outer border	29.3.1 Frame Layout
	outer edges	29.3.1 Frame Layout
	outer frame	29.3.1 Frame Layout
	outer height	29.3.1 Frame Layout
	outer position	29.3.1 Frame Layout
	outer size	29.3.1 Frame Layout
	outer width	29.3.1 Frame Layout
	`outer-window-id, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	output from processes	38.9 プロセスからの出力の受信
	output stream	19.4 出力ストリーム
	output-controlling variables	19.6 出力に影響する変数
	overall prompt string	22.3 キーマップのフォーマット
	overflow	3.1 整数の基礎
	`overflow-newline-into-fringe`	39.13.3 フリンジのカーソルFringe Cursors
	overlay properties	39.9.2 オーバーレイのプロパティ
	overlay, empty	39.9.1 オーバーレイの管理
	`overlay-arrow-position`	39.13.6 オーバーレイ矢印
	`overlay-arrow-string`	39.13.6 オーバーレイ矢印
	`overlay-arrow-variable-list`	39.13.6 オーバーレイ矢印
	`overlay-buffer`	39.9.1 オーバーレイの管理
	`overlay-end`	39.9.1 オーバーレイの管理
	`overlay-get`	39.9.2 オーバーレイのプロパティ
	`overlay-properties`	39.9.2 オーバーレイのプロパティ
	`overlay-put`	39.9.2 オーバーレイのプロパティ
	`overlay-recenter`	39.9.1 オーバーレイの管理
	`overlay-start`	39.9.1 オーバーレイの管理
	`overlayp`	39.9.1 オーバーレイの管理
	overlays	39.9 オーバーレイ
	overlays, managing	39.9.1 オーバーレイの管理
	overlays, scalability	39.9 オーバーレイ
	overlays, searching for	39.9.3 オーバーレイにたいする検索
	`overlays-at`	39.9.3 オーバーレイにたいする検索
	`overlays-in`	39.9.3 オーバーレイにたいする検索
	overlined text	39.12.1 フェイスの属性
	override existing functions	13.4 関数の定義
	override redirect frames	29.4.3.8 ウィンドウ管理のパラメーター
	override spec (for a face)	39.12.2 フェイスの定義
	`override-redirect, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	overriding bidirectional properties	39.26 双方向テキストの表示
	`overriding-local-map`	22.9 アクティブなキーマップの制御
	`overriding-local-map-menu-flag`	22.9 アクティブなキーマップの制御
	`overriding-terminal-local-map`	22.9 アクティブなキーマップの制御
	`overwrite-mode`	32.5 ユーザーレベルの挿入コマンド

P
	package	41 配布用 Lispコードの準備
	package archive	41.4 パッケージアーカイブの作成と保守
	package archive security	41.4 パッケージアーカイブの作成と保守
	package attributes	41.1 パッケージ化の基礎
	package autoloads	41.1 パッケージ化の基礎
	package dependencies	41.1 パッケージ化の基礎
	package name	41.1 パッケージ化の基礎
	package signing	41.4 パッケージアーカイブの作成と保守
	package version	41.1 パッケージ化の基礎
	`package-archive-upload-base`	41.4 パッケージアーカイブの作成と保守
	`package-archives`	41.4 パッケージアーカイブの作成と保守
	`package-initialize`	41.1 パッケージ化の基礎
	`package-upload-buffer`	41.4 パッケージアーカイブの作成と保守
	`package-upload-file`	41.4 パッケージアーカイブの作成と保守
	`package-version, customization keyword`	15.1 一般的なキーワードアイテム
	packing	38.20 バイト配列のpackとunpack
	padding	4.7 文字列のフォーマット
	`page-delimiter`	34.8 編集で使用される標準的な正規表現
	`paragraph-separate`	34.8 編集で使用される標準的な正規表現
	paragraph-separate, and bidirectional display	39.26 双方向テキストの表示
	`paragraph-start`	34.8 編集で使用される標準的な正規表現
	paragraph-start, and bidirectional display	39.26 双方向テキストの表示
	parameters for moving frames with the mouse	29.4.3.7 Mouse Dragging Parameters
	parameters for resizing frames with the mouse	29.4.3.7 Mouse Dragging Parameters
	parameters of initial frame	29.4.2 フレームの初期パラメーター
	parent frames	29.14 Child Frames
	parent of char-table	6.6 文字テーブル
	parent process	38 プロセス
	parent window	28.2 ウィンドウとフレーム
	parent window	28.2 ウィンドウとフレーム
	`parent-frame, a frame parameter`	29.4.3.6 Frame Interaction Parameters
	parenthesis	2.3.6 コンスセルとリスト型
	parenthesis depth	35.6.4 低レベルのパース
	parenthesis matching	39.21 カッコの点滅
	parenthesis mismatch, debugging	18.3 無効なLisp構文のデバッグ
	parity, in serial connections	38.19 シリアルポートとの対話
	parse state for a position	35.6.2 ある位置のパース状態を調べる
	`parse-colon-path`	40.3 オペレーティングシステムの環境
	`parse-partial-sexp`	35.6.4 低レベルのパース
	`parse-sexp-ignore-comments`	35.6.5 パースを制御するためのパラメーター
	`parse-sexp-lookup-properties`	35.4 構文プロパティ
	`parse-sexp-lookup-properties`	35.6.5 パースを制御するためのパラメーター
	parser state	35.6.3 パーサー状態
	parsing buffer text	35 構文テーブル
	parsing expressions	35.6 式のパース
	parsing html	32.28 HTMLとXMLの解析
	parsing xml	32.28 HTMLとXMLの解析
	parsing, control parameters	35.6.5 パースを制御するためのパラメーター
	partial application of functions	13.5 関数の呼び出し
	partial-width windows	39.3 切り詰め
	passwords, reading	20.9 パスワードの読み取り
	`PATH` environment variable	38.1 サブプロセスを作成する関数
	`path-separator`	40.3 オペレーティングシステムの環境
	pattern matching	11.2.1 パターンマッチングによるcase文
	PBM	39.17.7 その他のイメージタイプ
	`pcase`	11.2.1 パターンマッチングによるcase文
	pcase	11.2.1 パターンマッチングによるcase文
	`pcase-defmacro`	11.2.1 パターンマッチングによるcase文
	peculiar error	11.6.3.4 エラーシンボルとエラー条件
	peeking at input	21.8.6 その他のイベント入力の機能
	percent symbol in mode line	23.4.2 モードラインのデータ構造
	`perform-replace`	34.7 検索と置換
	performance analysis	18.5 プロファイリング
	performance analysis (Edebug)	18.2.13 カバレッジテスト
	permanent local variable	12.11.2 バッファーローカルなバインディングの作成と削除
	permissions, file	25.6.1 アクセシビリティのテスト
	permissions, file	25.7 ファイルの名前と属性の変更
	persistent window parameters	28.29 ウィンドウのパラメーター
	phishing using directional overrides	39.26 双方向テキストの表示
	piece of advice	13.11 Emacs Lisp関数にたいするアドバイス
	pipe	38.4 非同期プロセスの作成
	pixel height of a window	28.3 ウィンドウのサイズ
	pixel width of a window	28.3 ウィンドウのサイズ
	pixelwise, resizing windows	28.4 ウィンドウのリサイズ
	place form	12.17 ジェネリック変数
	`play-sound`	40.15 サウンドの出力
	`play-sound-file`	40.15 サウンドの出力
	`play-sound-functions`	40.15 サウンドの出力
	plist	5.9 プロパティリスト
	plist access	5.9.2 プロパティリストと外部シンボル
	plist vs. alist	5.9.1 プロパティリストと連想リスト
	`plist-get`	5.9.2 プロパティリストと外部シンボル
	`plist-member`	5.9.2 プロパティリストと外部シンボル
	`plist-put`	5.9.2 プロパティリストと外部シンボル
	`plugin_is_GPL_compatible`	16.11 Emacs Dynamic Modules
	`point`	30.1 ポイント
	point	30.1 ポイント
	point excursion	30.3 エクスカーション
	point excursion	30.3 エクスカーション
	point in window	28.21 ウィンドウとポイント
	point with narrowing	30.1 ポイント
	`point-entered (text property)`	32.19.4 特殊な意味をもつプロパティ
	`point-left (text property)`	32.19.4 特殊な意味をもつプロパティ
	`point-marker`	31.3 マーカーを作成する関数
	`point-max`	30.1 ポイント
	`point-max-marker`	31.3 マーカーを作成する関数
	`point-min`	30.1 ポイント
	`point-min-marker`	31.3 マーカーを作成する関数
	`pointer (text property)`	32.19.4 特殊な意味をもつプロパティ
	pointer shape	29.19 ポインターの形状
	pointers	2.3.6 コンスセルとリスト型
	polymorphism	13.8 Generic Functions
	`pop`	5.3 リスト要素へのアクセス
	`pop-mark`	31.7 マーク
	`pop-to-buffer`	28.12 ウィンドウ内のバッファーへの切り替え
	`pop-up-frame-alist`	28.15 バッファー表示の追加オプション
	`pop-up-frame-function`	28.15 バッファー表示の追加オプション
	`pop-up-frames`	28.15 バッファー表示の追加オプション
	`pop-up-windows`	28.15 バッファー表示の追加オプション
	port number, and default coding system	33.10.5 デフォルトのコーディングシステム
	`pos-visible-in-window-group-p`	28.22 ウィンドウの開始位置と終了位置
	`pos-visible-in-window-group-p-function`	28.22 ウィンドウの開始位置と終了位置
	`pos-visible-in-window-p`	28.22 ウィンドウの開始位置と終了位置
	position (in buffer)	30 ポジション
	position argument	21.2.2 `interactive`にたいするコード文字
	position in window	28.21 ウィンドウとポイント
	position of frame	29.3 Frame Geometry
	position of frame	29.3.3 Frame Position
	position of mouse	29.16 マウスの位置
	`position-bytes`	33.1 テキストの表現方法
	positive infinity	3.2 浮動小数点数の基礎
	`posix-looking-at`	34.5 POSIX正規表現の検索
	`posix-search-backward`	34.5 POSIX正規表現の検索
	`posix-search-forward`	34.5 POSIX正規表現の検索
	`posix-string-match`	34.5 POSIX正規表現の検索
	`posn-actual-col-row`	21.7.13 マウスイベントへのアクセス
	`posn-area`	21.7.13 マウスイベントへのアクセス
	`posn-at-point`	21.7.13 マウスイベントへのアクセス
	`posn-at-x-y`	21.7.13 マウスイベントへのアクセス
	`posn-col-row`	21.7.13 マウスイベントへのアクセス
	`posn-image`	21.7.13 マウスイベントへのアクセス
	`posn-object`	21.7.13 マウスイベントへのアクセス
	`posn-object-width-height`	21.7.13 マウスイベントへのアクセス
	`posn-object-x-y`	21.7.13 マウスイベントへのアクセス
	`posn-point`	21.7.13 マウスイベントへのアクセス
	`posn-string`	21.7.13 マウスイベントへのアクセス
	`posn-timestamp`	21.7.13 マウスイベントへのアクセス
	`posn-window`	21.7.13 マウスイベントへのアクセス
	`posn-x-y`	21.7.13 マウスイベントへのアクセス
	`posnp`	21.7.13 マウスイベントへのアクセス
	`post-command-hook`	21.1 コマンドループの概要
	`post-gc-hook`	E.3 ガーベージコレクション
	`post-self-insert-hook`	32.5 ユーザーレベルの挿入コマンド
	`pp`	19.5 出力関数
	`pre-command-hook`	21.1 コマンドループの概要
	`pre-redisplay-function`	39.2 強制的な再表示
	`pre-redisplay-functions`	39.2 強制的な再表示
	`preceding-char`	32.1 ポイント周辺のテキストを調べる
	precision in format specifications	4.7 文字列のフォーマット
	predicates for lists	5.2 リストのための述語
	predicates for markers	31.2 マーカーのための述語
	predicates for numbers	3.3 数値のための述語
	predicates for strings	4.2 文字列のための述語
	`prefer-utf-8 coding system`	33.10.1 コーディングシステムの基本概念
	prefix argument	21.12 プレフィクスコマンド引数
	prefix argument unreading	21.8.6 その他のイベント入力の機能
	prefix command	22.6 プレフィクスキー
	prefix key	22.6 プレフィクスキー
	`prefix, defgroup keyword`	15.2 カスタマイズグループの定義
	`prefix-arg`	21.12 プレフィクスコマンド引数
	`prefix-command-echo-keystrokes-functions`	Appendix H 標準的なフック
	`prefix-command-preserve-state-hook`	Appendix H 標準的なフック
	`prefix-help-command`	24.6 ヘルプ関数
	`prefix-numeric-value`	21.12 プレフィクスコマンド引数
	preloaded Lisp files	E.1 Emacsのビルド
	`preloaded-file-list`	E.1 Emacsのビルド
	preloading additional functions and variables	E.1 Emacsのビルド
	`prepare-change-group`	32.29 グループのアトミックな変更
	preserving window sizes	28.5 Preserving Window Sizes
	preventing backtracking	18.2.15.2 仕様リスト
	preventing prefix key	22.10 キーの照合
	preventing quitting	21.11 quit
	previous complete subexpression	35.6.3 パーサー状態
	`previous-button`	39.19.5 ボタンのためのバッファーコマンド
	`previous-char-property-change`	32.19.3 テキストプロパティの検索関数
	`previous-complete-history-element`	20.10 ミニバッファーのコマンド
	`previous-frame`	29.8 すべてのフレームを探す
	`previous-history-element`	20.10 ミニバッファーのコマンド
	`previous-matching-history-element`	20.10 ミニバッファーのコマンド
	`previous-overlay-change`	39.9.3 オーバーレイにたいする検索
	`previous-property-change`	32.19.3 テキストプロパティの検索関数
	`previous-single-char-property-change`	32.19.3 テキストプロパティの検索関数
	`previous-single-property-change`	32.19.3 テキストプロパティの検索関数
	`previous-window`	28.10 ウィンドウのサイクル順
	primary selection	29.20 ウィンドウシステムによる選択
	primitive	13.1 関数とは?
	primitive function	2.3.15 プリミティブ関数型
	primitive function internals	E.7 Emacsプリミティブの記述
	primitive type	2 Lispのデータ型
	`primitive-undo`	32.9 アンドゥ
	`prin1`	19.5 出力関数
	`prin1-to-string`	19.5 出力関数
	`princ`	19.5 出力関数
	`print`	19.5 出力関数
	print example	19.4 出力ストリーム
	print name cell	9.1 シンボルの構成要素
	`print-circle`	19.6 出力に影響する変数
	`print-continuous-numbering`	19.6 出力に影響する変数
	`print-escape-control-characters`	19.6 出力に影響する変数
	`print-escape-multibyte`	19.6 出力に影響する変数
	`print-escape-newlines`	19.6 出力に影響する変数
	`print-escape-nonascii`	19.6 出力に影響する変数
	`print-gensym`	19.6 出力に影響する変数
	`print-length`	19.6 出力に影響する変数
	`print-level`	19.6 出力に影響する変数
	`print-number-table`	19.6 出力に影響する変数
	`print-quoted`	19.6 出力に影響する変数
	printable ASCII characters	39.22.1 通常の表示の慣習
	`printable-chars`	33.6 文字のプロパティ
	printed representation	2.1 プリント表現と読み取り構文
	printed representation for characters	2.3.3.1 基本的な文字構文
	printing	19.1 読み取りとプリントの概念
	printing (Edebug)	18.2.11 Edebugでのプリント
	printing circular structures	18.2.11 Edebugでのプリント
	printing limits	19.6 出力に影響する変数
	printing notation	1.3.4 プリントの表記
	`priority (overlay property)`	39.9.2 オーバーレイのプロパティ
	priority order of coding systems	33.10.6 単一の操作にたいするコーディングシステムの指定
	process	38 プロセス
	process creation	38.1 サブプロセスを作成する関数
	process filter	38.9.2 プロセスのフィルター関数
	process filter multibyte flag	38.9.3 プロセス出力のデコード
	process information	38.6 プロセスの情報
	process input	38.7 プロセスへの入力の送信
	process internals	E.8.3 プロセスの内部
	process output	38.9 プロセスからの出力の受信
	process sentinel	38.10 センチネル: プロセス状態の変更の検知
	process signals	38.8 プロセスへのシグナルの送信
	`process-adaptive-read-buffering`	38.9 プロセスからの出力の受信
	`process-attributes`	38.12 別のプセスへのアクセス
	`process-buffer`	38.9.1 プロセスのバッファー
	`process-coding-system`	38.6 プロセスの情報
	`process-coding-system-alist`	33.10.5 デフォルトのコーディングシステム
	`process-command`	38.6 プロセスの情報
	`process-connection-type`	38.4 非同期プロセスの作成
	`process-contact`	38.6 プロセスの情報
	`process-datagram-address`	38.16 データグラム
	`process-environment`	40.3 オペレーティングシステムの環境
	`process-exit-status`	38.6 プロセスの情報
	`process-file`	38.3 同期プロセスの作成
	`process-file-shell-command`	38.3 同期プロセスの作成
	`process-file-side-effects`	38.3 同期プロセスの作成
	`process-filter`	38.9.2 プロセスのフィルター関数
	`process-get`	38.6 プロセスの情報
	`process-id`	38.6 プロセスの情報
	`process-kill-buffer-query-function`	38.9.1 プロセスのバッファー
	`process-lines`	38.3 同期プロセスの作成
	`process-list`	38.6 プロセスの情報
	`process-live-p`	38.6 プロセスの情報
	`process-mark`	38.9.1 プロセスのバッファー
	`process-name`	38.6 プロセスの情報
	`process-plist`	38.6 プロセスの情報
	`process-put`	38.6 プロセスの情報
	`process-query-on-exit-flag`	38.11 exit前の問い合わせ
	`process-running-child-p`	38.7 プロセスへの入力の送信
	`process-send-eof`	38.7 プロセスへの入力の送信
	`process-send-region`	38.7 プロセスへの入力の送信
	`process-send-string`	38.7 プロセスへの入力の送信
	`process-sentinel`	38.10 センチネル: プロセス状態の変更の検知
	`process-status`	38.6 プロセスの情報
	`process-thread`	38.9.5 Processes and Threads
	`process-tty-name`	38.6 プロセスの情報
	`process-type`	38.6 プロセスの情報
	processes, threads	38.9.5 Processes and Threads
	processing of errors	11.6.3.2 Emacsがエラーを処理する方法
	processor run time	40.9 プロセッサーの実行時間
	`processp`	38 プロセス
	profile	18.5 プロファイリング
	profiling	18.5 プロファイリング
	`prog-first-column`	32.17.2 メジャーモードが制御するインデント
	`prog-indentation-context`	32.17.2 メジャーモードが制御するインデント
	`prog-mode`	23.2.5 基本的なメジャーモード
	`prog-mode`, and `bidi-paragraph-direction`	39.26 双方向テキストの表示
	`prog-mode-hook`	23.2.5 基本的なメジャーモード
	`prog1`	11.1 順序
	`prog2`	11.1 順序
	`progn`	11.1 順序
	program arguments	38.1 サブプロセスを作成する関数
	program directories	38.1 サブプロセスを作成する関数
	program name, and default coding system	33.10.5 デフォルトのコーディングシステム
	programmed completion	20.6.7 プログラムされた補完
	programming conventions	D.3 Emacsプログラミングのヒント
	programming types	2.3 プログラミングの型
	progress reporting	39.4.2 処理の進捗レポート
	`progress-reporter-done`	39.4.2 処理の進捗レポート
	`progress-reporter-force-update`	39.4.2 処理の進捗レポート
	`progress-reporter-update`	39.4.2 処理の進捗レポート
	prompt for file name	20.6.5 ファイル名の読み取り
	prompt string (of menu)	22.17.1 メニューの定義
	prompt string of keymap	22.3 キーマップのフォーマット
	properties of text	32.19 テキストのプロパティ
	`propertize`	32.19.2 テキストプロパティの変更
	property category of text character	32.19.4 特殊な意味をもつプロパティ
	property list	5.9 プロパティリスト
	property list cell	9.1 シンボルの構成要素
	property lists vs association lists	5.9.1 プロパティリストと連想リスト
	protect C variables from garbage collection	E.7 Emacsプリミティブの記述
	protected forms	11.6.4 非ローカル脱出のクリーンアップ
	`provide`	16.7 名前つき機能
	`provide-theme`	15.6 カスタムテーマ
	providing features	16.7 名前つき機能
	pty	38.4 非同期プロセスの作成
	pure storage	E.2 純粋ストレージ
	`pure-bytes-used`	E.2 純粋ストレージ
	`purecopy`	E.2 純粋ストレージ
	`purify-flag`	E.2 純粋ストレージ
	`push`	5.5 リスト変数の変更
	`push-button`	39.19.5 ボタンのためのバッファーコマンド
	`push-mark`	31.7 マーク
	`put`	9.4.1 シンボルのプロパティへのアクセス
	`put-char-code-property`	33.6 文字のプロパティ
	`put-charset-property`	33.7 文字セット
	`put-image`	39.17.9 イメージの表示
	`put-text-property`	32.19.2 テキストプロパティの変更
	`puthash`	8.2 ハッシュテーブルへのアクセス

Q
	`query-font`	39.12.12 低レベルのフォント表現
	`query-replace-history`	20.4 ミニバッファーのヒストリー
	`query-replace-map`	34.7 検索と置換
	querying the user	20.7 Yes-or-Noによる問い合わせ
	question mark in character constant	2.3.3.1 基本的な文字構文
	`quietly-read-abbrev-file`	36.3 ファイルへのabbrevの保存
	`quit-flag`	21.11 quit
	`quit-process`	38.8 プロセスへのシグナルの送信
	`quit-restore, a window parameter`	28.29 ウィンドウのパラメーター
	`quit-restore-window`	28.18 ウィンドウのquit
	`quit-window`	28.18 ウィンドウのquit
	quitting	21.11 quit
	quitting from infinite loop	18.1.2 無限ループのデバッグ
	`quote`	10.3 クォート
	quote character	35.6.3 パーサー状態
	quote special characters in regexp	34.3.3 正規表現の関数
	quoted character input	21.8.5 クォートされた文字の入力
	`quoted-insert` suppression	22.12 キーバインディングの変更
	quoting and unquoting command-line arguments	38.2 shell引数
	quoting characters in printing	19.5 出力関数
	quoting using apostrophe	10.3 クォート

R
	radio, customization types	15.4.2 複合型
	radix for reading an integer	3.1 整数の基礎
	`raise-frame`	29.12 Raising, Lowering and Restacking Frames
	raising a frame	29.12 Raising, Lowering and Restacking Frames
	`random`	3.10 乱数
	random numbers	3.10 乱数
	`rassoc`	5.8 連想リスト
	`rassq`	5.8 連想リスト
	`rassq-delete-all`	5.8 連想リスト
	raw prefix argument	21.12 プレフィクスコマンド引数
	raw prefix argument usage	21.2.2 `interactive`にたいするコード文字
	raw syntax descriptor	35.7 構文テーブルの内部
	`raw-text coding system`	33.10.1 コーディングシステムの基本概念
	`re-builder`	34.3 正規表現
	`re-search-backward`	34.4 正規表現の検索
	`re-search-forward`	34.4 正規表現の検索
	`read`	19.3 入力関数
	read command name	21.3 interactiveな呼び出し
	read file names	20.6.5 ファイル名の読み取り
	read input	21.8 入力の読み取り
	read syntax	2.1 プリント表現と読み取り構文
	read syntax for characters	2.3.3.1 基本的な文字構文
	`read-buffer`	20.6.4 高レベルの補完関数
	`read-buffer-completion-ignore-case`	20.6.4 高レベルの補完関数
	`read-buffer-function`	20.6.4 高レベルの補完関数
	`read-char`	21.8.2 単一イベントの読み取り
	`read-char-choice`	21.8.2 単一イベントの読み取り
	`read-char-exclusive`	21.8.2 単一イベントの読み取り
	`read-circle`	19.3 入力関数
	`read-coding-system`	33.10.4 ユーザー選択のコーディングシステム
	`read-color`	20.6.4 高レベルの補完関数
	`read-command`	20.6.4 高レベルの補完関数
	`read-directory-name`	20.6.5 ファイル名の読み取り
	`read-event`	21.8.2 単一イベントの読み取り
	`read-expression-history`	20.4 ミニバッファーのヒストリー
	`read-file-modes`	25.7 ファイルの名前と属性の変更
	`read-file-name`	20.6.5 ファイル名の読み取り
	`read-file-name-completion-ignore-case`	20.6.5 ファイル名の読み取り
	`read-file-name-function`	20.6.5 ファイル名の読み取り
	`read-from-minibuffer`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`read-from-string`	19.3 入力関数
	`read-input-method-name`	33.11 入力メソッド
	`read-kbd-macro`	24.5 ヘルプメッセージの文字記述
	`read-key`	21.8.2 単一イベントの読み取り
	`read-key-sequence`	21.8.1 キーシーケンス入力
	`read-key-sequence-vector`	21.8.1 キーシーケンス入力
	`read-minibuffer`	20.3 ミニバッファーでのLispオブジェクトの読み取り
	`read-multiple-choice`	21.8.2 単一イベントの読み取り
	`read-no-blanks-input`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`read-non-nil-coding-system`	33.10.4 ユーザー選択のコーディングシステム
	`read-only (text property)`	32.19.4 特殊な意味をもつプロパティ
	read-only buffer	27.7 読み取り専用のバッファー
	read-only buffers in interactive	21.2.1 `interactive`の使用
	read-only character	32.19.4 特殊な意味をもつプロパティ
	read-only variables	12.2 変更不可な変数
	`read-only-mode`	27.7 読み取り専用のバッファー
	`read-passwd`	20.9 パスワードの読み取り
	`read-quoted-char`	21.8.5 クォートされた文字の入力
	`read-quoted-char` quitting	21.11 quit
	`read-regexp`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`read-regexp-defaults-function`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`read-shell-command`	20.6.5 ファイル名の読み取り
	`read-string`	20.2 ミニバッファーでのテキスト文字列の読み取り
	`read-variable`	20.6.4 高レベルの補完関数
	reading	19.1 読み取りとプリントの概念
	reading a single event	21.8.2 単一イベントの読み取り
	reading from files	25.3 ファイルの読み込み
	reading from minibuffer with completion	20.6.2 補完とミニバッファー
	reading interactive arguments	21.2.2 `interactive`にたいするコード文字
	reading numbers in hex, octal, and binary	3.1 整数の基礎
	reading order	39.26 双方向テキストの表示
	reading symbols	9.3 シンボルの作成とintern
	`real-last-command`	21.5 コマンドループからの情報
	rearrangement of lists	5.6.3 リストを再配置する関数
	rebinding	22.12 キーバインディングの変更
	`recent-auto-save-p`	26.2 自動保存
	`recent-keys`	40.13.2 入力の記録
	`recenter`	28.23 テキスト的なスクロール
	`recenter-positions`	28.23 テキスト的なスクロール
	`recenter-redisplay`	28.23 テキスト的なスクロール
	`recenter-top-bottom`	28.23 テキスト的なスクロール
	`recenter-window-group`	28.23 テキスト的なスクロール
	`recenter-window-group-function`	28.23 テキスト的なスクロール
	recombining windows	28.8 ウィンドウの再結合
	`record`	7.1 Record Functions
	record command history	21.3 interactiveな呼び出し
	recording input	40.13.2 入力の記録
	`recordp`	7.1 Record Functions
	records	7 Records
	rectangle, as contents of a register	32.21 レジスター
	recursion	11.4 繰り返し
	`recursion-depth`	21.13 再帰編集
	recursive command loop	21.13 再帰編集
	recursive editing level	21.13 再帰編集
	recursive evaluation	10.1 評価の概要
	recursive minibuffers	20.13 再帰的なミニバッファー
	`recursive-edit`	21.13 再帰編集
	redefine existing functions	13.4 関数の定義
	`redirect-frame-focus`	29.10 入力のフォーカス
	`redisplay`	39.2 強制的な再表示
	redo	32.9 アンドゥ
	`redraw-display`	39.1 スクリーンのリフレッシュ
	`redraw-frame`	39.1 スクリーンのリフレッシュ
	reducing sequences	6.1 シーケンス
	reference to free variable, compilation warning	17.6 コンパイラーのエラー
	references, following	D.2 キーバインディングの慣習
	refresh the screen	39.1 スクリーンのリフレッシュ
	regexp	34.3 正規表現
	regexp alternative	34.3.1.3 正規表現内のバッククラッシュ構造
	regexp grouping	34.3.1.3 正規表現内のバッククラッシュ構造
	regexp searching	34.4 正規表現の検索
	regexp syntax	34.3.1 正規表現の構文
	regexp, special characters in	34.3.1.1 正規表現内の特殊文字
	`regexp-history`	20.4 ミニバッファーのヒストリー
	`regexp-opt`	34.3.3 正規表現の関数
	`regexp-opt-charset`	34.3.3 正規表現の関数
	`regexp-opt-depth`	34.3.3 正規表現の関数
	`regexp-quote`	34.3.3 正規表現の関数
	regexps used standardly in editing	34.8 編集で使用される標準的な正規表現
	region	31.8 リージョン
	region argument	21.2.2 `interactive`にたいするコード文字
	`region-beginning`	31.8 リージョン
	`region-end`	31.8 リージョン
	register preview	32.21 レジスター
	`register-alist`	32.21 レジスター
	`register-read-with-preview`	32.21 レジスター
	registers	32.21 レジスター
	regular expression	34.3 正規表現
	regular expression searching	34.4 正規表現の検索
	regular expressions, developing	34.3 正規表現
	`reindent-then-newline-and-indent`	32.17.2 メジャーモードが制御するインデント
	relative file name	25.9.2 絶対ファイル名と相対ファイル名
	relative remapping, faces	39.12.5 フェイスのリマップ
	remainder	3.6 算術演算
	remapping commands	22.13 コマンドのリマップ
	`remhash`	8.2 ハッシュテーブルへのアクセス
	`remote-file-name-inhibit-cache`	25.12 特定のファイル名の“Magic”の作成
	`remove`	5.7 集合としてのリストの使用
	`remove-from-invisibility-spec`	39.6 不可視のテキスト
	`remove-function`	13.11.1 アドバイスを操作するためのプリミティブ
	`remove-hook`	23.1.2 フックのセットSetting Hooks
	`remove-images`	39.17.9 イメージの表示
	`remove-list-of-text-properties`	32.19.2 テキストプロパティの変更
	`remove-overlays`	39.9.1 オーバーレイの管理
	`remove-text-properties`	32.19.2 テキストプロパティの変更
	`remove-variable-watch`	12.9 Running a function when a variable is changed.
	removing from sequences	6.1 シーケンス
	`remq`	5.7 集合としてのリストの使用
	`rename-auto-save-file`	26.2 自動保存
	`rename-buffer`	27.3 バッファーの名前
	`rename-file`	25.7 ファイルの名前と属性の変更
	rendering html	32.28 HTMLとXMLの解析
	reordering, of bidirectional text	39.26 双方向テキストの表示
	reordering, of elements in lists	5.6.3 リストを再配置する関数
	reparent frame	29.14 Child Frames
	repeat events	21.7.7 リピートイベント
	repeated loading	16.6 多重ロード
	replace bindings	22.12 キーバインディングの変更
	replace characters	32.20 文字コードの置き換え
	replace characters in region	32.20 文字コードの置き換え
	replace list element	5.6.1 `setcar`によるリスト要素の変更
	replace matched text	34.6.1 マッチしたテキストの置換
	replace part of list	5.6.2 リストのCDRの変更
	`replace-buffer-contents`	32.23 Replacing Buffer Text
	`replace-buffer-in-windows`	28.11 バッファーとウィンドウ
	`replace-match`	34.6.1 マッチしたテキストの置換
	`replace-re-search-function`	34.7 検索と置換
	`replace-regexp-in-string`	34.7 検索と置換
	`replace-search-function`	34.7 検索と置換
	replacement after search	34.7 検索と置換
	replacing display specs	39.16.1 テキストを置換するディスプレー仕様
	`require`	16.7 名前つき機能
	`require, customization keyword`	15.1 一般的なキーワードアイテム
	`require-final-newline`	25.2 バッファーの保存
	requiring features	16.7 名前つき機能
	reserved keys	D.2 キーバインディングの慣習
	resize window	28.4 ウィンドウのリサイズ
	`resize-mini-windows`	20.11 ミニバッファーのウィンドウ
	rest arguments	13.2.3 引数リストのその他機能
	restacking a frame	29.12 Raising, Lowering and Restacking Frames
	`restore-buffer-modified-p`	27.5 バッファーの変更
	restricted-sexp, customization types	15.4.2 複合型
	restriction (in a buffer)	30.4 ナローイング
	resume (cf. `no-redraw-on-reenter`)	39.1 スクリーンのリフレッシュ
	`resume-tty`	40.2.2 Emacsのサスペンド
	`resume-tty-functions`	40.2.2 Emacsのサスペンド
	rethrow a signal	11.6.3.3 エラーを処理するコードの記述
	return (ASCII character)	2.3.3.1 基本的な文字構文
	return value	13.1 関数とは?
	`reverse`	6.1 シーケンス
	reversing a list	6.1 シーケンス
	reversing a string	6.1 シーケンス
	reversing a vector	6.1 シーケンス
	`revert-buffer`	26.3 リバート
	`revert-buffer-function`	26.3 リバート
	`revert-buffer-in-progress-p`	26.3 リバート
	`revert-buffer-insert-file-contents-function`	26.3 リバート
	`revert-without-query`	26.3 リバート
	reverting buffers	26.3 リバート
	rgb value	29.22 カラー名
	right dividers	39.15 ウィンドウディバイダー
	`right-divider-width, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`right-fringe, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`right-fringe-width`	39.13.1 フリンジのサイズと位置
	`right-margin-width`	39.16.5 マージン内への表示
	right-to-left text	39.26 双方向テキストの表示
	ring data structure	6.8 オブジェクト用固定長リングの管理
	`ring-bell-function`	39.23 ビープ
	`ring-copy`	6.8 オブジェクト用固定長リングの管理
	`ring-elements`	6.8 オブジェクト用固定長リングの管理
	`ring-empty-p`	6.8 オブジェクト用固定長リングの管理
	`ring-insert`	6.8 オブジェクト用固定長リングの管理
	`ring-insert-at-beginning`	6.8 オブジェクト用固定長リングの管理
	`ring-length`	6.8 オブジェクト用固定長リングの管理
	`ring-p`	6.8 オブジェクト用固定長リングの管理
	`ring-ref`	6.8 オブジェクト用固定長リングの管理
	`ring-remove`	6.8 オブジェクト用固定長リングの管理
	`ring-size`	6.8 オブジェクト用固定長リングの管理
	`risky, defcustom keyword`	15.3 カスタマイズ変数の定義
	`risky-local-variable-p`	12.12 ファイルローカル変数
	RLO	39.26 双方向テキストの表示
	`rm`	25.7 ファイルの名前と属性の変更
	root window	28.2 ウィンドウとフレーム
	root window of atomic window	28.20 Atomic Windows
	`round`	3.5 数値の変換
	rounding in conversions	3.5 数値の変換
	rounding without conversion	3.7 丸め処理
	`rplaca`	5.6 既存のリスト構造の変更
	`rplacd`	5.6 既存のリスト構造の変更
	run time stack	18.1.9 デバッガの内部
	`run-at-time`	40.11 遅延実行のためのタイマー
	`run-hook-with-args`	23.1.1 フックの実行
	`run-hook-with-args-until-failure`	23.1.1 フックの実行
	`run-hook-with-args-until-success`	23.1.1 フックの実行
	`run-hooks`	23.1.1 フックの実行
	`run-mode-hooks`	23.2.6 モードフック
	`run-window-configuration-change-hook`	28.30 ウィンドウのスクロールと変更のためのフック
	`run-window-scroll-functions`	28.30 ウィンドウのスクロールと変更のためのフック
	`run-with-idle-timer`	40.12 アイドルタイマー
	running a hook when a window gets selected	28.9 ウィンドウの選択

S
	S-expression	10.1 評価の概要
	safe local variable	12.12 ファイルローカル変数
	`safe, defcustom keyword`	15.3 カスタマイズ変数の定義
	`safe-length`	5.3 リスト要素へのアクセス
	`safe-local-eval-forms`	12.12 ファイルローカル変数
	`safe-local-variable-p`	12.12 ファイルローカル変数
	`safe-local-variable-values`	12.12 ファイルローカル変数
	`safe-magic (property)`	25.12 特定のファイル名の“Magic”の作成
	safely encode a string	33.10.3 Lispでのコーディングシステム
	safely encode characters in a charset	33.10.3 Lispでのコーディングシステム
	safely encode region	33.10.3 Lispでのコーディングシステム
	safety of functions	13.16 安全に関数を呼び出せるかどうかの判断
	`same-window-buffer-names`	28.15 バッファー表示の追加オプション
	`same-window-p`	28.15 バッファー表示の追加オプション
	`same-window-regexps`	28.15 バッファー表示の追加オプション
	save abbrevs in files	36.3 ファイルへのabbrevの保存
	`save-abbrevs`	36.3 ファイルへのabbrevの保存
	`save-buffer`	25.2 バッファーの保存
	`save-buffer-coding-system`	33.10.2 エンコーディングとI/O
	`save-current-buffer`	27.2 カレントバッファー
	`save-excursion`	30.3 エクスカーション
	`save-mark-and-excursion`	30.3 エクスカーション
	`save-match-data`	34.6.4 マッチデータの保存とリストア
	`save-restriction`	30.4 ナローイング
	`save-selected-window`	28.9 ウィンドウの選択
	`save-some-buffers`	25.2 バッファーの保存
	`save-some-buffers-default-predicate`	25.2 バッファーの保存
	`save-window-excursion`	28.28 ウィンドウの構成
	SaveUnder feature	29.25 ディスプレー機能のテスト
	saving buffers	25.2 バッファーの保存
	saving text properties	25.13 ファイルのフォーマット変換
	saving window information	28.28 ウィンドウの構成
	scalability of overlays	39.9 オーバーレイ
	scalable fonts	39.12.9 フォントの選択
	`scalable-fonts-allowed`	39.12.9 フォントの選択
	`scan-lists`	35.6.1 パースにもとづくモーションコマンド
	`scan-sexps`	35.6.1 パースにもとづくモーションコマンド
	scanning expressions	35.6 式のパース
	scanning for character sets	33.8 文字セットのスキャン
	scanning keymaps	22.16 キーマップのスキャン
	scope	12.10 変数のバインディングのスコーピングルール
	scoping rule	12.10 変数のバインディングのスコーピングルール
	screen layout	2.4.7 フレーム構成型
	screen lines, moving by	30.2.5 スクリーン行単位の移動
	screen of terminal	28.1 Emacsウィンドウの基本概念
	screen refresh	39.1 スクリーンのリフレッシュ
	`screen-gamma, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	script symbols	33.6 文字のプロパティ
	scroll bar events, data in	21.7.14 スクロールバーイベントへのアクセス
	scroll bars	39.14 スクロールバー
	`scroll-bar-background, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`scroll-bar-event-ratio`	21.7.14 スクロールバーイベントへのアクセス
	`scroll-bar-foreground, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`scroll-bar-height`	39.14 スクロールバー
	`scroll-bar-height, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`scroll-bar-mode`	39.14 スクロールバー
	`scroll-bar-scale`	21.7.14 スクロールバーイベントへのアクセス
	`scroll-bar-width`	39.14 スクロールバー
	`scroll-bar-width, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`scroll-command` property	28.23 テキスト的なスクロール
	`scroll-conservatively`	28.23 テキスト的なスクロール
	`scroll-down`	28.23 テキスト的なスクロール
	`scroll-down-aggressively`	28.23 テキスト的なスクロール
	`scroll-down-command`	28.23 テキスト的なスクロール
	`scroll-error-top-bottom`	28.23 テキスト的なスクロール
	`scroll-left`	28.25 水平スクロール
	`scroll-margin`	28.23 テキスト的なスクロール
	`scroll-other-window`	28.23 テキスト的なスクロール
	`scroll-preserve-screen-position`	28.23 テキスト的なスクロール
	`scroll-right`	28.25 水平スクロール
	`scroll-step`	28.23 テキスト的なスクロール
	`scroll-up`	28.23 テキスト的なスクロール
	`scroll-up-aggressively`	28.23 テキスト的なスクロール
	`scroll-up-command`	28.23 テキスト的なスクロール
	scrolling textually	28.23 テキスト的なスクロール
	`search-backward`	34.1 文字列の検索
	`search-failed`	34.1 文字列の検索
	`search-forward`	34.1 文字列の検索
	`search-map`	22.6 プレフィクスキー
	`search-spaces-regexp`	34.4 正規表現の検索
	searching	34 検索とマッチング
	searching active keymaps for keys	22.8 アクティブなキーマップの検索
	searching and case	34.2 検索と大文字小文字
	searching and replacing	34.7 検索と置換
	searching for overlays	39.9.3 オーバーレイにたいする検索
	searching for regexp	34.4 正規表現の検索
	searching text properties	32.19.3 テキストプロパティの検索関数
	secondary selection	29.20 ウィンドウシステムによる選択
	secondary storage	25.8 Files and Secondary Storage
	`seconds-to-time`	40.5 時刻
	`secure-hash`	32.26 チェックサムとハッシュ
	`secure-hash-algorithms`	32.26 チェックサムとハッシュ
	security	40.22 Security Considerations
	security, and display specifications	39.16 `display`プロパティ
	seed, for random number generation	3.10 乱数
	select safe coding system	33.10.4 ユーザー選択のコーディングシステム
	select window hook	28.9 ウィンドウの選択
	`select-frame`	29.10 入力のフォーカス
	`select-frame-set-input-focus`	29.10 入力のフォーカス
	`select-safe-coding-system`	33.10.4 ユーザー選択のコーディングシステム
	`select-safe-coding-system-accept-default-p`	33.10.4 ユーザー選択のコーディングシステム
	`select-safe-coding-system-function`	33.10.4 ユーザー選択のコーディングシステム
	`select-window`	28.9 ウィンドウの選択
	selected frame	29.10 入力のフォーカス
	selected window	28.1 Emacsウィンドウの基本概念
	`selected-frame`	29.10 入力のフォーカス
	`selected-window`	28.1 Emacsウィンドウの基本概念
	`selected-window-group`	28.1 Emacsウィンドウの基本概念
	`selected-window-group-function`	28.1 Emacsウィンドウの基本概念
	selecting a buffer	27.2 カレントバッファー
	selecting a font	39.12.9 フォントの選択
	selecting a window	28.9 ウィンドウの選択
	selection (for window systems)	29.20 ウィンドウシステムによる選択
	`selection-coding-system`	29.20 ウィンドウシステムによる選択
	`selective-display`	39.7 選択的な表示
	`selective-display-ellipses`	39.7 選択的な表示
	self-evaluating form	10.2.1 自己評価を行うフォーム
	`self-insert-and-exit`	20.10 ミニバッファーのコマンド
	`self-insert-command`	32.5 ユーザーレベルの挿入コマンド
	`self-insert-command` override	22.12 キーバインディングの変更
	`self-insert-command`, minor modes	23.3.2 キーマップとマイナーモード
	`self-insert-uses-region-functions`	32.5 ユーザーレベルの挿入コマンド
	self-insertion	32.5 ユーザーレベルの挿入コマンド
	SELinux context	25.6.5 拡張されたファイル属性
	`send-string-to-terminal`	40.14 端末の出力
	sending signals	38.8 プロセスへのシグナルの送信
	`sentence-end`	34.8 編集で使用される標準的な正規表現
	`sentence-end`	34.8 編集で使用される標準的な正規表現
	`sentence-end-double-space`	32.11 fill
	`sentence-end-without-period`	32.11 fill
	`sentence-end-without-space`	32.11 fill
	sentinel (of process)	38.10 センチネル: プロセス状態の変更の検知
	seq library	6.1 シーケンス
	`seq-concatenate`	6.1 シーケンス
	`seq-contains`	6.1 シーケンス
	`seq-count`	6.1 シーケンス
	`seq-difference`	6.1 シーケンス
	`seq-do`	6.1 シーケンス
	`seq-doseq`	6.1 シーケンス
	`seq-drop`	6.1 シーケンス
	`seq-drop-while`	6.1 シーケンス
	`seq-elt`	6.1 シーケンス
	`seq-empty-p`	6.1 シーケンス
	`seq-every-p`	6.1 シーケンス
	`seq-filter`	6.1 シーケンス
	`seq-find`	6.1 シーケンス
	`seq-group-by`	6.1 シーケンス
	`seq-intersection`	6.1 シーケンス
	`seq-into`	6.1 シーケンス
	`seq-length`	6.1 シーケンス
	`seq-let`	6.1 シーケンス
	`seq-map`	6.1 シーケンス
	`seq-map-indexed`	6.1 シーケンス
	`seq-mapcat`	6.1 シーケンス
	`seq-mapn`	6.1 シーケンス
	`seq-max`	6.1 シーケンス
	`seq-min`	6.1 シーケンス
	`seq-partition`	6.1 シーケンス
	`seq-position`	6.1 シーケンス
	`seq-random-elt`	6.1 シーケンス
	`seq-reduce`	6.1 シーケンス
	`seq-remove`	6.1 シーケンス
	`seq-set-equal-p`	6.1 シーケンス
	`seq-some`	6.1 シーケンス
	`seq-sort`	6.1 シーケンス
	`seq-sort-by`	6.1 シーケンス
	`seq-subseq`	6.1 シーケンス
	`seq-take`	6.1 シーケンス
	`seq-take-while`	6.1 シーケンス
	`seq-uniq`	6.1 シーケンス
	`seqp`	6.1 シーケンス
	sequence	6 シーケンス、配列、ベクター
	sequence destructuring	6.1 シーケンス
	sequence functions in seq	6.1 シーケンス
	sequence iteration	6.1 シーケンス
	sequence length	6.1 シーケンス
	sequence maximum	6.1 シーケンス
	sequence minimum	6.1 シーケンス
	sequence reverse	6.1 シーケンス
	`sequencep`	6.1 シーケンス
	sequences, generalized	6.1 シーケンス
	sequences, intersection of	6.1 シーケンス
	sequencing	11.1 順序
	sequential execution	11.1 順序
	serial connections	38.19 シリアルポートとの対話
	`serial-process-configure`	38.19 シリアルポートとの対話
	`serial-term`	38.19 シリアルポートとの対話
	serializing	38.20 バイト配列のpackとunpack
	session file	40.18 セッションマネージャー
	session manager	40.18 セッションマネージャー
	`set`	12.8 変数の値のセット
	`set, defcustom keyword`	15.3 カスタマイズ変数の定義
	`set-advertised-calling-convention`	13.12 関数を陳腐と宣言する
	`set-after, defcustom keyword`	15.3 カスタマイズ変数の定義
	`set-auto-coding`	33.10.5 デフォルトのコーディングシステム
	`set-auto-mode`	23.2.2 Emacsがメジャーモードを選択する方法
	`set-binary-mode`	19.3 入力関数
	`set-buffer`	27.2 カレントバッファー
	`set-buffer-auto-saved`	26.2 自動保存
	`set-buffer-major-mode`	23.2.2 Emacsがメジャーモードを選択する方法
	`set-buffer-modified-p`	27.5 バッファーの変更
	`set-buffer-multibyte`	33.4 表現の選択
	`set-case-syntax`	4.9 caseテーブル
	`set-case-syntax-delims`	4.9 caseテーブル
	`set-case-syntax-pair`	4.9 caseテーブル
	`set-case-table`	4.9 caseテーブル
	`set-category-table`	35.8 カテゴリー
	`set-char-table-extra-slot`	6.6 文字テーブル
	`set-char-table-parent`	6.6 文字テーブル
	`set-char-table-range`	6.6 文字テーブル
	`set-charset-priority`	33.7 文字セット
	`set-coding-system-priority`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`set-default`	12.11.3 バッファーローカル変数のデフォルト値
	`set-default-file-modes`	25.7 ファイルの名前と属性の変更
	`set-default-toplevel-value`	12.11.3 バッファーローカル変数のデフォルト値
	`set-display-table-slot`	39.22.2 ディスプレーテーブル
	`set-face-attribute`	39.12.3 フェイス属性のための関数
	`set-face-background`	39.12.3 フェイス属性のための関数
	`set-face-bold`	39.12.3 フェイス属性のための関数
	`set-face-font`	39.12.3 フェイス属性のための関数
	`set-face-foreground`	39.12.3 フェイス属性のための関数
	`set-face-inverse-video`	39.12.3 フェイス属性のための関数
	`set-face-italic`	39.12.3 フェイス属性のための関数
	`set-face-stipple`	39.12.3 フェイス属性のための関数
	`set-face-underline`	39.12.3 フェイス属性のための関数
	`set-file-acl`	25.7 ファイルの名前と属性の変更
	`set-file-extended-attributes`	25.7 ファイルの名前と属性の変更
	`set-file-modes`	25.7 ファイルの名前と属性の変更
	`set-file-selinux-context`	25.7 ファイルの名前と属性の変更
	`set-file-times`	25.7 ファイルの名前と属性の変更
	`set-fontset-font`	39.12.11 フォントセット
	`set-frame-configuration`	29.13 フレーム構成
	`set-frame-font`	29.3.2 Frame Font
	`set-frame-height`	29.3.4 Frame Size
	`set-frame-parameter`	29.4.1 フレームパラメーターへのアクセス
	`set-frame-position`	29.3.3 Frame Position
	`set-frame-selected-window`	28.9 ウィンドウの選択
	`set-frame-size`	29.3.4 Frame Size
	`set-frame-width`	29.3.4 Frame Size
	`set-fringe-bitmap-face`	39.13.5 フリンジビットマップのカスタマイズ
	`set-input-method`	33.11 入力メソッド
	`set-input-mode`	40.13.1 入力のモード
	`set-keyboard-coding-system`	33.10.8 端末I/Oのエンコーディング
	`set-keymap-parent`	22.5 継承とキーマップ
	`set-left-margin`	32.12 fillのマージン
	`set-mark`	31.7 マーク
	`set-marker`	31.6 マーカー位置の移動
	`set-marker-insertion-type`	31.5 Marker 挿入タイプ
	`set-match-data`	34.6.3 マッチデータ全体へのアクセス
	`set-minibuffer-window`	20.11 ミニバッファーのウィンドウ
	`set-mouse-absolute-pixel-position`	29.16 マウスの位置
	`set-mouse-pixel-position`	29.16 マウスの位置
	`set-mouse-position`	29.16 マウスの位置
	`set-network-process-option`	38.17.2 ネットワークのオプション
	`set-process-buffer`	38.9.1 プロセスのバッファー
	`set-process-coding-system`	38.6 プロセスの情報
	`set-process-datagram-address`	38.16 データグラム
	`set-process-filter`	38.9.2 プロセスのフィルター関数
	`set-process-plist`	38.6 プロセスの情報
	`set-process-query-on-exit-flag`	38.11 exit前の問い合わせ
	`set-process-sentinel`	38.10 センチネル: プロセス状態の変更の検知
	`set-process-thread`	38.9.5 Processes and Threads
	`set-process-window-size`	38.9.1 プロセスのバッファー
	`set-register`	32.21 レジスター
	`set-right-margin`	32.12 fillのマージン
	`set-standard-case-table`	4.9 caseテーブル
	`set-syntax-table`	35.3 構文テーブルの関数
	`set-terminal-coding-system`	33.10.8 端末I/Oのエンコーディング
	`set-terminal-parameter`	29.5 端末のパラメーター
	`set-text-properties`	32.19.2 テキストプロパティの変更
	`set-transient-map`	22.9 アクティブなキーマップの制御
	`set-visited-file-modtime`	27.6 バッファーの変更 Time
	`set-visited-file-name`	27.4 バッファーのファイル名
	`set-window-buffer`	28.11 バッファーとウィンドウ
	`set-window-combination-limit`	28.8 ウィンドウの再結合
	`set-window-configuration`	28.28 ウィンドウの構成
	`set-window-dedicated-p`	28.17 専用のウィンドウ
	`set-window-display-table`	39.22.3 アクティブなディスプレーテーブル
	`set-window-fringes`	39.13.1 フリンジのサイズと位置
	`set-window-group-start`	28.22 ウィンドウの開始位置と終了位置
	`set-window-group-start-function`	28.22 ウィンドウの開始位置と終了位置
	`set-window-hscroll`	28.25 水平スクロール
	`set-window-margins`	39.16.5 マージン内への表示
	`set-window-next-buffers`	28.16 ウィンドウのヒストリー
	`set-window-parameter`	28.29 ウィンドウのパラメーター
	`set-window-point`	28.21 ウィンドウとポイント
	`set-window-prev-buffers`	28.16 ウィンドウのヒストリー
	`set-window-scroll-bars`	39.14 スクロールバー
	`set-window-start`	28.22 ウィンドウの開始位置と終了位置
	`set-window-vscroll`	28.24 割り合いによる垂直スクロール
	`set-xwidget-plist`	39.18 Embedded Native Widgets
	`set-xwidget-query-on-exit-flag`	39.18 Embedded Native Widgets
	`setcar`	5.6.1 `setcar`によるリスト要素の変更
	`setcdr`	5.6.2 リストのCDRの変更
	`setenv`	40.3 オペレーティングシステムの環境
	`setf`	12.17.1 `setf`マクロ
	`setplist`	9.4.1 シンボルのプロパティへのアクセス
	`setq`	12.8 変数の値のセット
	`setq-default`	12.11.3 バッファーローカル変数のデフォルト値
	`setq-local`	12.11.2 バッファーローカルなバインディングの作成と削除
	sets	5.7 集合としてのリストの使用
	setting modes of files	25.7 ファイルの名前と属性の変更
	`setting-constant` error	12.2 変更不可な変数
	severity level	39.5.1 警告の基礎
	sexp	10.1 評価の概要
	sexp motion	30.2.6 バランスのとれたカッコを越えた移動
	SHA hash	32.26 チェックサムとハッシュ
	SHA hash	32.27 GnuTLS Cryptography
	shadowed Lisp files	16.3 ライブラリー検索
	shadowing of variables	12.3 ローカル変数
	shared structure, read syntax	2.5 循環オブジェクトの読み取り構文
	shell command arguments	38.2 shell引数
	`shell-command-history`	20.4 ミニバッファーのヒストリー
	`shell-command-to-string`	38.3 同期プロセスの作成
	`shell-quote-argument`	38.2 shell引数
	shift-selection, and `interactive` spec	21.2.1 `interactive`の使用
	shift-translation	21.8.1 キーシーケンス入力
	show image	39.17.9 イメージの表示
	`show-help-function`	32.19.4 特殊な意味をもつプロパティ
	`shr-insert-document`	32.28 HTMLとXMLの解析
	`shrink-window-if-larger-than-buffer`	28.4 ウィンドウのリサイズ
	shy groups	34.3.1.3 正規表現内のバッククラッシュ構造
	sibling window	28.2 ウィンドウとフレーム
	side effect	10.1 評価の概要
	side windows	28.19 Side Windows
	SIGHUP	40.2.1 Emacsのkill
	SIGINT	40.2.1 Emacsのkill
	`signal`	11.6.3.1 エラーをシグナルする方法
	`signal-process`	38.8 プロセスへのシグナルの送信
	signaling errors	11.6.3.1 エラーをシグナルする方法
	signals	38.8 プロセスへのシグナルの送信
	SIGTERM	40.2.1 Emacsのkill
	SIGTSTP	40.2.2 Emacsのサスペンド
	`sigusr1` event	21.7.10 その他のシステムイベント
	`sigusr2` event	21.7.10 その他のシステムイベント
	simple package	41.2 単純なパッケージ
	`sin`	3.9 標準的な数学関数
	single file package	41.2 単純なパッケージ
	single-function hook	23.1 フック
	`single-key-description`	24.5 ヘルプメッセージの文字記述
	`sit-for`	21.10 時間の経過や入力の待機
	`site-init.el`	E.1 Emacsのビルド
	site-lisp directories	16.3 ライブラリー検索
	`site-load.el`	E.1 Emacsのビルド
	`site-run-file`	40.1.2 initファイル
	`site-start.el`	40.1.1 要約: スタートアップ時のアクション順序
	size of frame	29.3 Frame Geometry
	size of image	39.17.9 イメージの表示
	size of text on display	39.10 表示されるテキストのサイズ
	size of window	28.3 ウィンドウのサイズ
	`skip-chars-backward`	30.2.7 文字のスキップ
	`skip-chars-forward`	30.2.7 文字のスキップ
	`skip-syntax-backward`	35.5 モーションと構文
	`skip-syntax-forward`	35.5 モーションと構文
	`skip-taskbar, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	skipping characters	30.2.7 文字のスキップ
	skipping characters of certain syntax	35.5 モーションと構文
	skipping comments	35.6.5 パースを制御するためのパラメーター
	`sleep-for`	21.10 時間の経過や入力の待機
	slice, image	39.17.9 イメージの表示
	`small-temporary-file-directory`	25.9.5 一意なファイル名の生成
	smallest Lisp integer	3.1 整数の基礎
	SMIE	23.7.1 SMIE: 無邪気なインデントエンジン
	SMIE grammar	23.7.1.3 言語の文法の定義
	SMIE lexer	23.7.1.4 トークンの定義
	`smie-bnf->prec2`	23.7.1.2 演算子順位文法
	`smie-close-block`	23.7.1.1 SMIEのセットアップと機能
	`smie-config`	23.7.1.9 インデントのカスタマイズ
	`smie-config-guess`	23.7.1.9 インデントのカスタマイズ
	`smie-config-local`	23.7.1.9 インデントのカスタマイズ
	`smie-config-save`	23.7.1.9 インデントのカスタマイズ
	`smie-config-set-indent`	23.7.1.9 インデントのカスタマイズ
	`smie-config-show-indent`	23.7.1.9 インデントのカスタマイズ
	`smie-down-list`	23.7.1.1 SMIEのセットアップと機能
	`smie-merge-prec2s`	23.7.1.2 演算子順位文法
	`smie-prec2->grammar`	23.7.1.2 演算子順位文法
	`smie-precs->prec2`	23.7.1.2 演算子順位文法
	`smie-rule-bolp`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-hanging-p`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-next-p`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-parent`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-parent-p`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-prev-p`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-separator`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-rule-sibling-p`	23.7.1.7 インデントルールにたいするヘルパー関数
	`smie-setup`	23.7.1.1 SMIEのセットアップと機能
	`snap-width, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	`Snarf-documentation`	24.2 ドキュメント文字列へのアクセス
	`sort`	6.1 シーケンス
	`sort-columns`	32.15 テキストのソート
	`sort-fields`	32.15 テキストのソート
	`sort-fold-case`	32.15 テキストのソート
	`sort-lines`	32.15 テキストのソート
	`sort-numeric-base`	32.15 テキストのソート
	`sort-numeric-fields`	32.15 テキストのソート
	`sort-pages`	32.15 テキストのソート
	`sort-paragraphs`	32.15 テキストのソート
	`sort-regexp-fields`	32.15 テキストのソート
	`sort-subr`	32.15 テキストのソート
	sorting lists	6.1 シーケンス
	sorting sequences	6.1 シーケンス
	sorting text	32.15 テキストのソート
	sorting vectors	6.1 シーケンス
	sound	40.15 サウンドの出力
	source breakpoints	18.2.6.3 ソースブレークポイント
	space (ASCII character)	2.3.3.1 基本的な文字構文
	`space` display spec, and bidirectional text	39.26 双方向テキストの表示
	spaces, pixel specification	39.16.3 スペースにたいするピクセル指定
	spaces, specified height or width	39.16.2 スペースの指定
	sparse keymap	22.3 キーマップのフォーマット
	`SPC` in minibuffer	20.2 ミニバッファーでのテキスト文字列の読み取り
	special events	21.9 スペシャルイベント
	special form descriptions	1.3.7.1 関数の説明例
	special forms	10.2.7 スペシャルフォーム
	special forms for control structures	11 制御構造
	`special` modes	23.2.1 メジャーモードの慣習
	special variables	12.10.4 レキシカルバインディングの使用
	`special-event-map`	22.9 アクティブなキーマップの制御
	`special-form-p`	10.2.7 スペシャルフォーム
	`special-mode`	23.2.5 基本的なメジャーモード
	`special-variable-p`	12.10.4 レキシカルバインディングの使用
	specify coding system	33.10.6 単一の操作にたいするコーディングシステムの指定
	specify color	29.22 カラー名
	speedups	D.4 コンパイル済みコードを高速化ためのヒント
	splicing (with backquote)	10.4 バッククォート
	`split-height-threshold`	28.15 バッファー表示の追加オプション
	`split-string`	4.3 文字列の作成
	`split-string-and-unquote`	38.2 shell引数
	`split-string-default-separators`	4.3 文字列の作成
	`split-width-threshold`	28.15 バッファー表示の追加オプション
	`split-window`	28.6 ウィンドウの分割
	`split-window, a window parameter`	28.29 ウィンドウのパラメーター
	`split-window-below`	28.6 ウィンドウの分割
	`split-window-keep-point`	28.6 ウィンドウの分割
	`split-window-preferred-function`	28.15 バッファー表示の追加オプション
	`split-window-right`	28.6 ウィンドウの分割
	`split-window-sensibly`	28.15 バッファー表示の追加オプション
	splitting windows	28.6 ウィンドウの分割
	`sqrt`	3.9 標準的な数学関数
	stable sort	6.1 シーケンス
	stack allocated Lisp objects	E.4 Stack-allocated Objects
	standard abbrev tables	36.5 標準的なabbrevテーブル
	standard colors for character terminals	29.4.3.10 フォントとカラーのパラメーター
	standard errors	Appendix F 標準的なエラー
	standard hooks	Appendix H 標準的なフック
	standard regexps used in editing	34.8 編集で使用される標準的な正規表現
	standard syntax table	35.1 構文テーブルの概念
	`standard-case-table`	4.9 caseテーブル
	`standard-category-table`	35.8 カテゴリー
	`standard-display-table`	39.22.3 アクティブなディスプレーテーブル
	`standard-input`	19.3 入力関数
	`standard-output`	19.6 出力に影響する変数
	`standard-syntax-table`	35.1 構文テーブルの概念
	`standard-translation-table-for-decode`	33.9 文字の変換
	`standard-translation-table-for-encode`	33.9 文字の変換
	standards of coding style	Appendix D ヒントと規約
	`start-file-process`	38.4 非同期プロセスの作成
	`start-file-process-shell-command`	38.4 非同期プロセスの作成
	`start-process`	38.4 非同期プロセスの作成
	`start-process`, command-line arguments from minibuffer	38.2 shell引数
	`start-process-shell-command`	38.4 非同期プロセスの作成
	STARTTLS network connections	38.14 ネットワーク接続
	startup of Emacs	40.1.1 要約: スタートアップ時のアクション順序
	startup screen	40.1.1 要約: スタートアップ時のアクション順序
	`startup.el`	40.1.1 要約: スタートアップ時のアクション順序
	`staticpro`, protection from GC	E.7 Emacsプリミティブの記述
	`stderr` stream, use for debugging	19.4 出力ストリーム
	sticky text properties	32.19.6 テキストプロパティの粘着性
	`sticky, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	stop points	18.2.1 Edebugの使用
	`stop-process`	38.8 プロセスへのシグナルの送信
	stopbits, in serial connections	38.19 シリアルポートとの対話
	stopping an infinite loop	18.1.2 無限ループのデバッグ
	stopping on events	18.2.6.2 グローバルなブレーク条件
	storage of vector-like Lisp objects	E.3 ガーベージコレクション
	`store-match-data`	34.6.3 マッチデータ全体へのアクセス
	`store-substring`	4.4 文字列の変更
	stream (for printing)	19.4 出力ストリーム
	stream (for reading)	19.2 入力ストリーム
	strike-through text	39.12.1 フェイスの属性
	`string`	4.3 文字列の作成
	string creation	4.3 文字列の作成
	string equality	4.5 文字および文字列の比較
	string in keymap	22.10 キーの照合
	string input stream	19.2 入力ストリーム
	string length	6.1 シーケンス
	string modification	4.4 文字列の変更
	string predicates	4.2 文字列のための述語
	string reverse	6.1 シーケンス
	string search	34.1 文字列の検索
	string to number	4.6 文字および文字列の変換
	string to object	19.3 入力関数
	string to vector	6.1 シーケンス
	string, number of bytes	33.1 テキストの表現方法
	string, writing a doc string	24.1 ドキュメントの基礎
	`string-as-multibyte`	33.4 表現の選択
	`string-as-unibyte`	33.4 表現の選択
	`string-bytes`	33.1 テキストの表現方法
	`string-chars-consed`	E.5 メモリー使用量
	`string-collate-equalp`	4.5 文字および文字列の比較
	`string-collate-lessp`	4.5 文字および文字列の比較
	`string-equal`	4.5 文字および文字列の比較
	`string-greaterp`	4.5 文字および文字列の比較
	`string-lessp`	4.5 文字および文字列の比較
	`string-match`	34.4 正規表現の検索
	`string-match-p`	34.4 正規表現の検索
	`string-or-null-p`	4.2 文字列のための述語
	`string-prefix-p`	4.5 文字および文字列の比較
	`string-suffix-p`	4.5 文字および文字列の比較
	`string-to-char`	4.6 文字および文字列の変換
	`string-to-int`	4.6 文字および文字列の変換
	`string-to-multibyte`	33.3 テキスト表現の変換
	`string-to-number`	4.6 文字および文字列の変換
	`string-to-syntax`	35.7 構文テーブルの内部
	`string-to-unibyte`	33.3 テキスト表現の変換
	`string-version-lessp`	4.5 文字および文字列の比較
	`string-width`	39.10 表示されるテキストのサイズ
	`string<`	4.5 文字および文字列の比較
	`string=`	4.5 文字および文字列の比較
	`stringp`	4.2 文字列のための述語
	strings	4 文字列と文字
	strings with keyboard events	21.7.15 文字列内へのキーボードイベントの配置
	strings, formatting them	4.7 文字列のフォーマット
	`strings-consed`	E.5 メモリー使用量
	sub-sequence	6.1 シーケンス
	submenu	22.17.2 メニューとマウス
	subprocess	38 プロセス
	subr	13.1 関数とは?
	`subr-arity`	13.1 関数とは?
	`subrp`	13.1 関数とは?
	`subst-char-in-region`	32.20 文字コードの置き換え
	substitute characters	32.20 文字コードの置き換え
	`substitute-command-keys`	24.3 ドキュメント内でのキーバインディングの置き換え
	`substitute-in-file-name`	25.9.4 ファイル名を展開する関数
	`substitute-key-definition`	22.12 キーバインディングの変更
	substituting keys in documentation	24.3 ドキュメント内でのキーバインディングの置き換え
	`substring`	4.3 文字列の作成
	`substring-no-properties`	4.3 文字列の作成
	subtype of char-table	6.6 文字テーブル
	suggestions	1.1 注意事項
	super characters	2.3.3.5 その他の文字修飾ビット
	`suppress-keymap`	22.12 キーバインディングの変更
	surrogate minibuffer frame	29.9 ミニバッファーとフレーム
	suspend (cf. `no-redraw-on-reenter`)	39.1 スクリーンのリフレッシュ
	suspend evaluation	21.13 再帰編集
	`suspend-emacs`	40.2.2 Emacsのサスペンド
	`suspend-frame`	40.2.2 Emacsのサスペンド
	`suspend-hook`	40.2.2 Emacsのサスペンド
	`suspend-resume-hook`	40.2.2 Emacsのサスペンド
	`suspend-tty`	40.2.2 Emacsのサスペンド
	`suspend-tty-functions`	40.2.2 Emacsのサスペンド
	suspending Emacs	40.2.2 Emacsのサスペンド
	SVG images	39.17.6 SVG Images
	`svg-circle`	39.17.6 SVG Images
	`svg-create`	39.17.6 SVG Images
	`svg-ellipse`	39.17.6 SVG Images
	`svg-embed`	39.17.6 SVG Images
	`svg-gradient`	39.17.6 SVG Images
	`svg-line`	39.17.6 SVG Images
	`svg-polygon`	39.17.6 SVG Images
	`svg-polyline`	39.17.6 SVG Images
	`svg-rectangle`	39.17.6 SVG Images
	`svg-remove`	39.17.6 SVG Images
	`svg-text`	39.17.6 SVG Images
	swap text between buffers	27.12 2つのバッファー間でのテキストの交換
	`switch-to-buffer`	28.12 ウィンドウ内のバッファーへの切り替え
	`switch-to-buffer-in-dedicated-window`	28.12 ウィンドウ内のバッファーへの切り替え
	`switch-to-buffer-other-frame`	28.12 ウィンドウ内のバッファーへの切り替え
	`switch-to-buffer-other-window`	28.12 ウィンドウ内のバッファーへの切り替え
	`switch-to-buffer-preserve-window-point`	28.12 ウィンドウ内のバッファーへの切り替え
	`switch-to-next-buffer`	28.16 ウィンドウのヒストリー
	`switch-to-prev-buffer`	28.16 ウィンドウのヒストリー
	`switch-to-visible-buffer`	28.16 ウィンドウのヒストリー
	switches on command line	40.1.4 コマンドライン引数
	switching to a buffer	28.12 ウィンドウ内のバッファーへの切り替え
	`sxhash-eq`	8.3 ハッシュの比較の定義
	`sxhash-eql`	8.3 ハッシュの比較の定義
	`sxhash-equal`	8.3 ハッシュの比較の定義
	symbol	9 シンボル
	symbol components	9.1 シンボルの構成要素
	symbol equality	9.3 シンボルの作成とintern
	symbol evaluation	10.2.2 シンボルのフォーム
	symbol function indirection	10.2.4 シンボル関数インダイレクション
	symbol in keymap	22.10 キーの照合
	symbol name hashing	9.3 シンボルの作成とintern
	symbol property	9.4 シンボルのプロパティ
	symbol that evaluates to itself	12.2 変更不可な変数
	symbol with constant value	12.2 変更不可な変数
	symbol, where defined	16.8 どのファイルで特定のシンボルが定義されているか
	`symbol-file`	16.8 どのファイルで特定のシンボルが定義されているか
	`symbol-function`	13.9 関数セルの内容へのアクセス
	`symbol-name`	9.3 シンボルの作成とintern
	`symbol-plist`	9.4.1 シンボルのプロパティへのアクセス
	`symbol-value`	12.7 変数の値へのアクセス
	symbolic links	25.6.2 ファイル種別の区別
	symbolic links	25.6.2 ファイル種別の区別
	`symbolp`	9 シンボル
	`symbols-consed`	E.5 メモリー使用量
	symmetric cipher	32.27 GnuTLS Cryptography
	synchronous subprocess	38.3 同期プロセスの作成
	syntactic font lock	23.6.8 構文的なFont Lock
	syntax class	35.2 構文記述子
	syntax class table	35.2.1 構文クラスのテーブル
	syntax code	35.7 構文テーブルの内部
	syntax descriptor	35.2 構文記述子
	syntax entry, setting	35.3 構文テーブルの関数
	syntax error (Edebug)	18.2.15.3 仕様でのバックトレース
	syntax flags	35.2.2 構文フラグ
	syntax for characters	2.3.3.1 基本的な文字構文
	syntax of regular expressions	34.3.1 正規表現の構文
	syntax table	35 構文テーブル
	syntax table example	23.2.9 メジャーモードの例
	syntax table internals	35.7 構文テーブルの内部
	syntax tables (accessing elements of)	35.7 構文テーブルの内部
	syntax tables in modes	23.2.1 メジャーモードの慣習
	`syntax-after`	35.7 構文テーブルの内部
	`syntax-class`	35.7 構文テーブルの内部
	`syntax-ppss`	35.6.2 ある位置のパース状態を調べる
	`syntax-ppss-flush-cache`	35.6.2 ある位置のパース状態を調べる
	`syntax-ppss-toplevel-pos`	35.6.3 パーサー状態
	`syntax-propertize-extend-region-functions`	35.4 構文プロパティ
	`syntax-propertize-function`	35.4 構文プロパティ
	`syntax-table`	35.3 構文テーブルの関数
	`syntax-table (text property)`	35.4 構文プロパティ
	`syntax-table-p`	35.1 構文テーブルの概念
	system abbrev	36 abbrevとabbrev展開
	system processes	38.12 別のプセスへのアクセス
	system type and name	40.3 オペレーティングシステムの環境
	`system-configuration`	40.3 オペレーティングシステムの環境
	`system-groups`	40.4 ユーザーの識別
	`system-key-alist`	40.16 X11キーシンボルの処理
	`system-messages-locale`	33.12 locale
	`system-name`	40.3 オペレーティングシステムの環境
	`system-time-locale`	33.12 locale
	`system-type`	40.3 オペレーティングシステムの環境
	`system-users`	40.4 ユーザーの識別

T
	`t`	1.3.2 `nil`と`t`
	`t` input stream	19.2 入力ストリーム
	`t` output stream	19.4 出力ストリーム
	tab (ASCII character)	2.3.3.1 基本的な文字構文
	tab deletion	32.6 テキストの削除
	`TAB` in minibuffer	20.2 ミニバッファーでのテキスト文字列の読み取り
	`tab-always-indent`	32.17.2 メジャーモードが制御するインデント
	`tab-stop-list`	32.17.5 Adjustable Tab Stops
	`tab-to-tab-stop`	32.17.5 Adjustable Tab Stops
	`tab-width`	39.22.1 通常の表示の慣習
	tabs stops for indentation	32.17.5 Adjustable Tab Stops
	Tabulated List mode	23.2.7 Tabulated Listモード
	`tabulated-list-entries`	23.2.7 Tabulated Listモード
	`tabulated-list-format`	23.2.7 Tabulated Listモード
	`tabulated-list-init-header`	23.2.7 Tabulated Listモード
	`tabulated-list-mode`	23.2.7 Tabulated Listモード
	`tabulated-list-print`	23.2.7 Tabulated Listモード
	`tabulated-list-printer`	23.2.7 Tabulated Listモード
	`tabulated-list-revert-hook`	23.2.7 Tabulated Listモード
	`tabulated-list-sort-key`	23.2.7 Tabulated Listモード
	tag on run time stack	11.6.1 明示的な非ローカル脱出: `catch`と`throw`
	`tag, customization keyword`	15.1 一般的なキーワードアイテム
	`tan`	3.9 標準的な数学関数
	TCP	38.14 ネットワーク接続
	`temacs`	E.1 Emacsのビルド
	`TEMP` environment variable	25.9.5 一意なファイル名の生成
	`temp-buffer-max-height`	39.8 一時的な表示
	`temp-buffer-max-width`	39.8 一時的な表示
	`temp-buffer-resize-mode`	39.8 一時的な表示
	`temp-buffer-setup-hook`	39.8 一時的な表示
	`temp-buffer-show-function`	39.8 一時的な表示
	`temp-buffer-show-hook`	39.8 一時的な表示
	`temp-buffer-window-setup-hook`	39.8 一時的な表示
	`temp-buffer-window-show-hook`	39.8 一時的な表示
	temporary buffer display	39.8 一時的な表示
	temporary display	39.8 一時的な表示
	temporary files	25.9.5 一意なファイル名の生成
	`temporary-file-directory`	25.9.5 一意なファイル名の生成
	`temporary-file-directory`	25.9.5 一意なファイル名の生成
	`TERM` environment variable	40.1.3 端末固有の初期化
	`term-file-aliases`	40.1.3 端末固有の初期化
	`term-file-prefix`	40.1.3 端末固有の初期化
	Termcap	40.1.3 端末固有の初期化
	terminal	29 フレーム
	terminal input	40.13 端末の入力
	terminal input modes	40.13.1 入力のモード
	terminal output	40.14 端末の出力
	terminal parameters	29.5 端末のパラメーター
	terminal screen	28.1 Emacsウィンドウの基本概念
	terminal type	2.4.5 端末型
	`terminal-coding-system`	33.10.8 端末I/Oのエンコーディング
	`terminal-list`	29.2 複数の端末
	`terminal-live-p`	29 フレーム
	terminal-local variables	29.2 複数の端末
	`terminal-name`	29.2 複数の端末
	`terminal-parameter`	29.5 端末のパラメーター
	`terminal-parameters`	29.5 端末のパラメーター
	terminal-specific initialization	40.1.3 端末固有の初期化
	termscript file	40.14 端末の出力
	`terpri`	19.5 出力関数
	`test-completion`	20.6.1 基本的な補完関数
	`testcover-mark-all`	18.4 カバレッジテスト
	`testcover-next-mark`	18.4 カバレッジテスト
	`testcover-start`	18.4 カバレッジテスト
	testing types	2.6 型のための述語
	text	32 テキスト
	text area	29.3.1 Frame Layout
	text area of a window	28.3 ウィンドウのサイズ
	text comparison	4.5 文字および文字列の比較
	text conversion of coding system	33.10.3 Lispでのコーディングシステム
	text deletion	32.6 テキストの削除
	text height of a frame	29.3.4 Frame Size
	text insertion	32.4 テキストの挿入
	text near point	32.1 ポイント周辺のテキストを調べる
	text parsing	35 構文テーブル
	text properties	32.19 テキストのプロパティ
	text properties in files	25.13 ファイルのフォーマット変換
	text properties in the mode line	23.4.6 モードラインでのプロパティ
	text properties, changing	32.19.2 テキストプロパティの変更
	text properties, examining	32.19.1 テキストプロパティを調べる
	text properties, read syntax	2.3.8.4 文字列内のテキストプロパティ
	text properties, searching	32.19.3 テキストプロパティの検索関数
	text representation	33.1 テキストの表現方法
	text size of a frame	29.3.4 Frame Size
	text terminal	29 フレーム
	text width of a frame	29.3.4 Frame Size
	`text-char-description`	24.5 ヘルプメッセージの文字記述
	`text-mode`	23.2.5 基本的なメジャーモード
	`text-mode-abbrev-table`	36.5 標準的なabbrevテーブル
	`text-properties-at`	32.19.1 テキストプロパティを調べる
	`text-property-any`	32.19.3 テキストプロパティの検索関数
	`text-property-default-nonsticky`	32.19.6 テキストプロパティの粘着性
	`text-property-not-all`	32.19.3 テキストプロパティの検索関数
	`text-quoting-style`	24.3 ドキュメント内でのキーバインディングの置き換え
	`text-quoting-style`	24.4 Text Quoting Style
	textual order	11 制御構造
	textual scrolling	28.23 テキスト的なスクロール
	`thing-at-point`	32.2 バッファーのコンテンツを調べる
	`this-command`	21.5 コマンドループからの情報
	`this-command-keys`	21.5 コマンドループからの情報
	`this-command-keys-shift-translated`	21.8.1 キーシーケンス入力
	`this-command-keys-vector`	21.5 コマンドループからの情報
	`this-original-command`	21.5 コマンドループからの情報
	`thread--blocker`	37.1 Basic Thread Functions
	`thread-alive-p`	37.1 Basic Thread Functions
	`thread-join`	37.1 Basic Thread Functions
	`thread-last-error`	37.1 Basic Thread Functions
	`thread-name`	37.1 Basic Thread Functions
	`thread-signal`	37.1 Basic Thread Functions
	`thread-yield`	37.1 Basic Thread Functions
	`threadp`	37.1 Basic Thread Functions
	threads	37 Threads
	`three-step-help`	24.6 ヘルプ関数
	`throw`	11.6.1 明示的な非ローカル脱出: `catch`と`throw`
	`throw` example	21.13 再帰編集
	tiled windows	28.1 Emacsウィンドウの基本概念
	time calculations	40.10 時間の計算
	time conversion	40.7 時刻の変換
	time formatting	40.8 時刻のパースとフォーマット
	time of day	40.5 時刻
	time parsing	40.8 時刻のパースとフォーマット
	time value	40.5 時刻
	time zone rule	40.6 Time Zone Rules
	time zone rules	40.6 Time Zone Rules
	time zone, current	40.6 Time Zone Rules
	`time-add`	40.10 時間の計算
	`time-less-p`	40.10 時間の計算
	`time-subtract`	40.10 時間の計算
	`time-to-day-in-year`	40.10 時間の計算
	`time-to-days`	40.10 時間の計算
	`timer-max-repeats`	40.11 遅延実行のためのタイマー
	`timerp`	40.11 遅延実行のためのタイマー
	timers	40.11 遅延実行のためのタイマー
	timestamp of a mouse event	21.7.13 マウスイベントへのアクセス
	timing programs	18.5 プロファイリング
	tips for writing Lisp	Appendix D ヒントと規約
	title bar	29.3.1 Frame Layout
	`title, a frame parameter`	29.4.3.1 基本パラメーター
	TLS network connections	38.14 ネットワーク接続
	`TMP` environment variable	25.9.5 一意なファイル名の生成
	`TMPDIR` environment variable	25.9.5 一意なファイル名の生成
	`toggle-enable-multibyte-characters`	33.2 マルチバイト文字の無効化
	tool bar	22.17.6 ツールバー
	`tool-bar-add-item`	22.17.6 ツールバー
	`tool-bar-add-item-from-menu`	22.17.6 ツールバー
	`tool-bar-border`	22.17.6 ツールバー
	`tool-bar-button-margin`	22.17.6 ツールバー
	`tool-bar-button-relief`	22.17.6 ツールバー
	`tool-bar-lines, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`tool-bar-local-item-from-menu`	22.17.6 ツールバー
	`tool-bar-map`	22.17.6 ツールバー
	`tool-bar-position, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	`tooltip face`	39.25 Tooltips
	tooltip for help strings	32.19.4 特殊な意味をもつプロパティ
	tooltip frames	39.25 Tooltips
	`tooltip-event-buffer`	39.25 Tooltips
	`tooltip-frame-parameters`	39.25 Tooltips
	`tooltip-functions`	39.25 Tooltips
	`tooltip-help-tips`	39.25 Tooltips
	`tooltip-mode`	39.25 Tooltips
	tooltips	39.25 Tooltips
	top frame	29.12 Raising, Lowering and Restacking Frames
	top position ratio	29.4.3.2 位置のパラメーター
	`top, a frame parameter`	29.4.3.2 位置のパラメーター
	`top-level`	21.13 再帰編集
	top-level default value	12.11.3 バッファーローカル変数のデフォルト値
	top-level form	16 ロード
	top-level frame	29 フレーム
	`top-visible, a frame parameter`	29.4.3.7 Mouse Dragging Parameters
	total height of a window	28.3 ウィンドウのサイズ
	total pixel height of a window	28.3 ウィンドウのサイズ
	total pixel width of a window	28.3 ウィンドウのサイズ
	total width of a window	28.3 ウィンドウのサイズ
	`tq-close`	38.13 トランザクションキュー
	`tq-create`	38.13 トランザクションキュー
	`tq-enqueue`	38.13 トランザクションキュー
	trace buffer	18.2.12 トレースバッファー
	tracing Lisp programs	18 Lispプログラムのデバッグ
	`track-mouse`	29.15 マウスの追跡
	tracking frame size changes	29.3.4 Frame Size
	trailing blanks in file names	25.6 ファイルの情報
	transaction queue	38.13 トランザクションキュー
	transcendental functions	3.9 標準的な数学関数
	transient keymap	22.9 アクティブなキーマップの制御
	`transient-mark-mode`	31.7 マーク
	`translate-region`	32.20 文字コードの置き換え
	translating input events	21.8.3 入力イベントの変更と変換
	translation keymap	22.14 イベントシーケンス変換のためのキーマップ
	translation tables	33.9 文字の変換
	`translation-table-for-input`	33.9 文字の変換
	transparency, frame	29.4.3.10 フォントとカラーのパラメーター
	`transpose-regions`	32.22 テキストの交換
	trash	25.7 ファイルの名前と属性の変更
	trash	25.11 ディレクトリーの作成・コピー・削除
	tray notifications, MS-Windows	40.19 デスクトップ通知
	triple-click events	21.7.7 リピートイベント
	true	1.3.2 `nil`と`t`
	true list	5.1 リストとコンスセル
	truename (of file)	25.6.3 本当の名前
	`truncate`	3.5 数値の変換
	`truncate-lines`	39.3 切り詰め
	`truncate-partial-width-windows`	39.3 切り詰め
	`truncate-string-ellipsis`	39.10 表示されるテキストのサイズ
	`truncate-string-to-width`	39.10 表示されるテキストのサイズ
	truth value	1.3.2 `nil`と`t`
	`try-completion`	20.6.1 基本的な補完関数
	`tty-color-alist`	29.23 テキスト端末のカラー
	`tty-color-approximate`	29.23 テキスト端末のカラー
	`tty-color-clear`	29.23 テキスト端末のカラー
	`tty-color-define`	29.23 テキスト端末のカラー
	`tty-color-mode, a frame parameter`	29.4.3.10 フォントとカラーのパラメーター
	`tty-color-translate`	29.23 テキスト端末のカラー
	`tty-erase-char`	40.3 オペレーティングシステムの環境
	`tty-setup-hook`	40.1.3 端末固有の初期化
	`tty-top-frame`	29.12 Raising, Lowering and Restacking Frames
	turn multibyte support on or off	33.2 マルチバイト文字の無効化
	two’s complement	3.1 整数の基礎
	type	2 Lispのデータ型
	`type (button property)`	39.19.1 ボタンのプロパティ
	type checking	2.6 型のための述語
	type checking internals	E.7 Emacsプリミティブの記述
	type predicates	2.6 型のための述語
	`type, defcustom keyword`	15.4 カスタマイズ型
	`type-of`	2.6 型のための述語
	typographic conventions	1.3.1 用語について
	`TZ, environment variable`	40.6 Time Zone Rules

U
	UBA	39.26 双方向テキストの表示
	UDP	38.14 ネットワーク接続
	UID	40.4 ユーザーの識別
	umask	25.7 ファイルの名前と属性の変更
	unassigned character codepoints	33.6 文字のプロパティ
	unbalanced parentheses	18.3 無効なLisp構文のデバッグ
	unbinding keys	22.15 キーのバインドのためのコマンド
	`unbury-buffer`	27.8 バッファーリスト
	`undecided coding system`	33.10.1 コーディングシステムの基本概念
	`undecided` coding-system, when encoding	33.10.7 明示的なエンコードとデコード
	`undecorated, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`undefined`	22.11 キー照合のための関数
	`undefined` in keymap	22.10 キーの照合
	undefined key	22.2 キーマップの基礎
	`underline-minimum-offset`	39.12.1 フェイスの属性
	underlined text	39.12.1 フェイスの属性
	undo avoidance	32.20 文字コードの置き換え
	`undo-ask-before-discard`	32.10 アンドゥリストの保守
	`undo-auto-amalgamate`	32.9 アンドゥ
	`undo-auto-current-boundary-timer`	32.9 アンドゥ
	`undo-boundary`	32.9 アンドゥ
	`undo-in-progress`	32.9 アンドゥ
	`undo-limit`	32.10 アンドゥリストの保守
	`undo-outer-limit`	32.10 アンドゥリストの保守
	`undo-strong-limit`	32.10 アンドゥリストの保守
	unexec	E.1 Emacsのビルド
	`unhandled-file-name-directory`	25.12 特定のファイル名の“Magic”の作成
	unibyte buffers, and bidi reordering	39.26 双方向テキストの表示
	unibyte text	33.1 テキストの表現方法
	`unibyte-char-to-multibyte`	33.3 テキスト表現の変換
	`unibyte-string`	33.1 テキストの表現方法
	Unicode	33.1 テキストの表現方法
	unicode bidirectional algorithm	39.26 双方向テキストの表示
	unicode character escape	2.3.3.2 一般的なエスケープ構文
	unicode general category	33.6 文字のプロパティ
	`unicode`, a charset	33.7 文字セット
	`unicode-category-table`	33.6 文字のプロパティ
	`unintern`	9.3 シンボルの作成とintern
	uninterned symbol	9.3 シンボルの作成とintern
	unique file names	25.9.5 一意なファイル名の生成
	`universal-argument`	21.12 プレフィクスコマンド引数
	`universal-argument-map`	Appendix G 標準的なキーマップ
	`unless`	11.2 条件
	`unload-feature`	16.9 アンロード
	`unload-feature-special-hooks`	16.9 アンロード
	unloading packages	16.9 アンロード
	unloading packages, preparing for	D.1 Emacs Lispコーディングの慣習
	`unlock-buffer`	25.5 ファイルのロック
	unmapped frame	29.11 フレームの可視性
	unnumbered group	34.3.1.3 正規表現内のバッククラッシュ構造
	unpacking	38.20 バイト配列のpackとunpack
	`unread-command-events`	21.8.6 その他のイベント入力の機能
	`unsafep`	13.16 安全に関数を呼び出せるかどうかの判断
	`unsplittable, a frame parameter`	29.4.3.5 バッファーのパラメーター
	unused lexical variable	12.10.4 レキシカルバインディングの使用
	`unwind-protect`	11.6.4 非ローカル脱出のクリーンアップ
	unwinding	11.6.4 非ローカル脱出のクリーンアップ
	`up-list`	30.2.6 バランスのとれたカッコを越えた移動
	`upcase`	4.8 Lispでの大文字小文字変換
	`upcase-initials`	4.8 Lispでの大文字小文字変換
	`upcase-region`	32.18 大文字小文字の変更
	`upcase-word`	32.18 大文字小文字の変更
	`update-directory-autoloads`	16.5 autoload
	`update-file-autoloads`	16.5 autoload
	upper case	4.8 Lispでの大文字小文字変換
	upper case key sequence	21.8.1 キーシーケンス入力
	uptime of Emacs	40.9 プロセッサーの実行時間
	use time of window	28.9 ウィンドウの選択
	`use-empty-active-region`	31.8 リージョン
	`use-global-map`	22.9 アクティブなキーマップの制御
	`use-hard-newlines`	32.11 fill
	`use-local-map`	22.9 アクティブなキーマップの制御
	`use-region-p`	31.8 リージョン
	user errors, signaling	11.6.3.1 エラーをシグナルする方法
	user groups	40.4 ユーザーの識別
	user identification	40.4 ユーザーの識別
	user options, how to define	15.3 カスタマイズ変数の定義
	user signals	21.7.10 その他のシステムイベント
	user-defined error	11.6.3.4 エラーシンボルとエラー条件
	`user-emacs-directory`	40.1.2 initファイル
	`user-error`	11.6.3.1 エラーをシグナルする方法
	`user-full-name`	40.4 ユーザーの識別
	`user-full-name`	40.4 ユーザーの識別
	`user-init-file`	40.1.2 initファイル
	`user-login-name`	40.4 ユーザーの識別
	`user-login-name`	40.4 ユーザーの識別
	`user-mail-address`	40.4 ユーザーの識別
	`user-position, a frame parameter`	29.4.3.2 位置のパラメーター
	user-ptr object	16.11 Emacs Dynamic Modules
	`user-ptrp`	16.11 Emacs Dynamic Modules
	`user-real-login-name`	40.4 ユーザーの識別
	`user-real-login-name`	40.4 ユーザーの識別
	`user-real-uid`	40.4 ユーザーの識別
	`user-size, a frame parameter`	29.4.3.3 サイズのパラメーター
	`user-uid`	40.4 ユーザーの識別
	`utf-8-emacs coding system`	33.10.1 コーディングシステムの基本概念

V
	valid windows	28.1 Emacsウィンドウの基本概念
	validity of coding system	33.10.3 Lispでのコーディングシステム
	value cell	9.1 シンボルの構成要素
	value of expression	10 評価
	value of function	13.1 関数とは?
	`values`	10.5 eval
	variable	12 変数
	variable aliases	12.15 変数のエイリアス
	variable definition	12.5 グローバル変数の定義
	variable descriptions	1.3.7.2 変数の説明例
	variable limit error	12.3 ローカル変数
	variable watchpoints	12.9 Running a function when a variable is changed.
	variable with constant value	12.2 変更不可な変数
	variable write debugging	18.1.4 Entering the debugger when a variable is modified
	variable, buffer-local	12.11 バッファーローカル変数
	`variable-documentation` property	24.1 ドキュメントの基礎
	variable-width spaces	39.16.2 スペースの指定
	variant coding system	33.10.1 コーディングシステムの基本概念
	`vc-mode`	23.4.4 モードラインで使用される変数
	`vc-prefix-map`	22.6 プレフィクスキー
	`vc-responsible-backend`	25.6.3 本当の名前
	`vconcat`	6.5 ベクターのための関数
	`vector`	6.5 ベクターのための関数
	vector (type)	6.4 ベクター
	vector evaluation	10.2.1 自己評価を行うフォーム
	vector length	6.1 シーケンス
	vector reverse	6.1 シーケンス
	vector to list	6.1 シーケンス
	`vector-cells-consed`	E.5 メモリー使用量
	vector-like objects, storage	E.3 ガーベージコレクション
	`vectorp`	6.5 ベクターのための関数
	`verify-visited-file-modtime`	27.6 バッファーの変更 Time
	version number (in file name)	25.9.1 ファイル名の構成要素
	`version, customization keyword`	15.1 一般的なキーワードアイテム
	`version-control`	26.1.3 番号つきバックアップファイルの作成と削除
	vertical combination	28.2 ウィンドウとフレーム
	vertical fractional scrolling	28.24 割り合いによる垂直スクロール
	vertical scroll position	28.24 割り合いによる垂直スクロール
	vertical tab	2.3.3.1 基本的な文字構文
	`vertical-line` prefix key	21.8.1 キーシーケンス入力
	`vertical-motion`	30.2.5 スクリーン行単位の移動
	`vertical-scroll-bar`	39.14 スクロールバー
	`vertical-scroll-bar` prefix key	21.8.1 キーシーケンス入力
	`vertical-scroll-bars, a frame parameter`	29.4.3.4 レイアウトのパラメーター
	view part, model/view/controller	39.20 抽象的なディスプレー
	`view-register`	32.21 レジスター
	virtual buffers	27.12 2つのバッファー間でのテキストの交換
	`visibility, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	visible frame	29.11 フレームの可視性
	`visible-bell`	39.23 ビープ
	`visible-frame-list`	29.8 すべてのフレームを探す
	visited file	27.4 バッファーのファイル名
	visited file mode	23.2.2 Emacsがメジャーモードを選択する方法
	`visited-file-modtime`	27.6 バッファーの変更 Time
	visiting files	25.1 ファイルのvisit
	visiting files, functions for	25.1.1 ファイルをvisitする関数
	visual order	39.26 双方向テキストの表示
	visual order, preserve when copying bidirectional text	39.26 双方向テキストの表示
	visual-order cursor motion	39.26 双方向テキストの表示
	void function	10.2.4 シンボル関数インダイレクション
	void function cell	13.9 関数セルの内容へのアクセス
	void variable	12.4 When a Variable is Void
	`void-function`	13.9 関数セルの内容へのアクセス
	`void-text-area-pointer`	29.19 ポインターの形状
	`void-variable` error	12.4 When a Variable is Void

W
	`w32-collate-ignore-punctuation`	4.5 文字および文字列の比較
	`w32-notification-close`	40.19 デスクトップ通知
	`w32-notification-notify`	40.19 デスクトップ通知
	`wait-for-wm, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	waiting	21.10 時間の経過や入力の待機
	waiting for command key input	21.8.6 その他のイベント入力の機能
	`waiting-for-user-input-p`	38.10 センチネル: プロセス状態の変更の検知
	`walk-windows`	28.10 ウィンドウのサイクル順
	`warn`	39.5.1 警告の基礎
	warning options	39.5.3 警告のためのオプション
	warning type	39.5.1 警告の基礎
	warning variables	39.5.2 警告のための変数
	`warning-fill-prefix`	39.5.2 警告のための変数
	`warning-levels`	39.5.2 警告のための変数
	`warning-minimum-level`	39.5.3 警告のためのオプション
	`warning-minimum-log-level`	39.5.3 警告のためのオプション
	`warning-prefix-function`	39.5.2 警告のための変数
	`warning-series`	39.5.2 警告のための変数
	`warning-suppress-log-types`	39.5.3 警告のためのオプション
	`warning-suppress-types`	39.5.3 警告のためのオプション
	`warning-type-format`	39.5.2 警告のための変数
	warnings	39.5 警告のレポート
	watch, for filesystem events	40.20 ファイル変更による通知
	watchpoints for Lisp variables	12.9 Running a function when a variable is changed.
	webkit browser widget	39.18 Embedded Native Widgets
	`wheel-down` event	21.7.10 その他のシステムイベント
	`wheel-up` event	21.7.10 その他のシステムイベント
	`when`	11.2 条件
	where was a symbol defined	16.8 どのファイルで特定のシンボルが定義されているか
	`where-is-internal`	22.16 キーマップのスキャン
	`while`	11.4 繰り返し
	`while-no-input`	21.8.6 その他のイベント入力の機能
	`while-no-input-ignore-events`	21.8.6 その他のイベント入力の機能
	whitespace	2.3.3.1 基本的な文字構文
	`wholenump`	3.3 数値のための述語
	`widen`	30.4 ナローイング
	widening	30.4 ナローイング
	width of a window	28.3 ウィンドウのサイズ
	`width, a frame parameter`	29.4.3.3 サイズのパラメーター
	window	28.1 Emacsウィンドウの基本概念
	`window (overlay property)`	39.9.2 オーバーレイのプロパティ
	window auto-selection	28.27 Mouse Window Auto-selection
	window body	28.3 ウィンドウのサイズ
	window body height	28.3 ウィンドウのサイズ
	window body size	28.3 ウィンドウのサイズ
	window body width	28.3 ウィンドウのサイズ
	window combination	28.2 ウィンドウとフレーム
	window combination limit	28.8 ウィンドウの再結合
	window configuration (Edebug)	18.2.14.2 Edebugの表示の更新
	window configurations	28.28 ウィンドウの構成
	window dividers	39.15 ウィンドウディバイダー
	window end position	28.22 ウィンドウの開始位置と終了位置
	window excursions	30.3 エクスカーション
	window header line	23.4.7 ウィンドウのヘッダーライン
	window height	28.3 ウィンドウのサイズ
	window history	28.16 ウィンドウのヒストリー
	window in direction	28.2 ウィンドウとフレーム
	window internals	E.8.2 ウィンドウの内部
	window layout in a frame	2.4.6 ウィンドウ構成型
	window layout, all frames	2.4.7 フレーム構成型
	window manager interaction, and frame parameters	29.4.3.8 ウィンドウ管理のパラメーター
	window order by time of last use	28.9 ウィンドウの選択
	window ordering, cyclic	28.10 ウィンドウのサイクル順
	window parameters	28.29 ウィンドウのパラメーター
	window pixel height	28.3 ウィンドウのサイズ
	window pixel width	28.3 ウィンドウのサイズ
	window point	28.21 ウィンドウとポイント
	window point internals	E.8.2 ウィンドウの内部
	window position	28.21 ウィンドウとポイント
	window position	28.26 座標とウィンドウ
	window position on display	29.4.3.2 位置のパラメーター
	window positions and window managers	29.4.3.2 位置のパラメーター
	window resizing	28.4 ウィンドウのリサイズ
	window selected within a frame	28.1 Emacsウィンドウの基本概念
	window size	28.3 ウィンドウのサイズ
	window size on display	29.4.3.3 サイズのパラメーター
	window size, changing	28.4 ウィンドウのリサイズ
	window splitting	28.6 ウィンドウの分割
	window start position	28.22 ウィンドウの開始位置と終了位置
	window state	28.28 ウィンドウの構成
	window that satisfies a predicate	28.10 ウィンドウのサイクル順
	window top line	28.22 ウィンドウの開始位置と終了位置
	window tree	28.2 ウィンドウとフレーム
	window use time	28.9 ウィンドウの選択
	window width	28.3 ウィンドウのサイズ
	`window-absolute-body-pixel-edges`	28.26 座標とウィンドウ
	`window-absolute-pixel-edges`	28.26 座標とウィンドウ
	`window-absolute-pixel-position`	28.26 座標とウィンドウ
	`window-adjust-process-window-size-function`	38.9.1 プロセスのバッファー
	`window-at`	28.26 座標とウィンドウ
	`window-at-side-p`	28.2 ウィンドウとフレーム
	`window-atom, a window parameter`	28.29 ウィンドウのパラメーター
	`window-atom-root`	28.20 Atomic Windows
	`window-body-edges`	28.26 座標とウィンドウ
	`window-body-height`	28.3 ウィンドウのサイズ
	`window-body-pixel-edges`	28.26 座標とウィンドウ
	`window-body-size`	28.3 ウィンドウのサイズ
	`window-body-width`	28.3 ウィンドウのサイズ
	`window-bottom-divider-width`	39.15 ウィンドウディバイダー
	`window-buffer`	28.11 バッファーとウィンドウ
	`window-child`	28.2 ウィンドウとフレーム
	`window-combination-limit`	28.8 ウィンドウの再結合
	`window-combination-limit`	28.8 ウィンドウの再結合
	`window-combination-resize`	28.8 ウィンドウの再結合
	`window-combined-p`	28.2 ウィンドウとフレーム
	`window-configuration-change-hook`	28.30 ウィンドウのスクロールと変更のためのフック
	`window-configuration-frame`	28.28 ウィンドウの構成
	`window-configuration-p`	28.28 ウィンドウの構成
	`window-current-scroll-bars`	39.14 スクロールバー
	`window-dedicated-p`	28.17 専用のウィンドウ
	`window-display-table`	39.22.3 アクティブなディスプレーテーブル
	`window-edges`	28.26 座標とウィンドウ
	`window-end`	28.22 ウィンドウの開始位置と終了位置
	`window-font-height`	39.12.12 低レベルのフォント表現
	`window-font-width`	39.12.12 低レベルのフォント表現
	`window-frame`	28.2 ウィンドウとフレーム
	`window-fringes`	39.13.1 フリンジのサイズと位置
	`window-full-height-p`	28.3 ウィンドウのサイズ
	`window-full-width-p`	28.3 ウィンドウのサイズ
	`window-group-end`	28.22 ウィンドウの開始位置と終了位置
	`window-group-end-function`	28.22 ウィンドウの開始位置と終了位置
	`window-group-start`	28.22 ウィンドウの開始位置と終了位置
	`window-group-start-function`	28.22 ウィンドウの開始位置と終了位置
	`window-header-line-height`	23.4.7 ウィンドウのヘッダーライン
	`window-header-line-height`	28.3 ウィンドウのサイズ
	`window-hscroll`	28.25 水平スクロール
	`window-id, a frame parameter`	29.4.3.8 ウィンドウ管理のパラメーター
	`window-in-direction`	28.2 ウィンドウとフレーム
	`window-largest-empty-rectangle`	28.26 座標とウィンドウ
	`window-left-child`	28.2 ウィンドウとフレーム
	`window-line-height`	28.22 ウィンドウの開始位置と終了位置
	`window-lines-pixel-dimensions`	39.10 表示されるテキストのサイズ
	`window-list`	28.2 ウィンドウとフレーム
	`window-live-p`	28.1 Emacsウィンドウの基本概念
	`window-main-window`	28.19.2 Side Window Options and Functions
	`window-make-atom`	28.20 Atomic Windows
	`window-margins`	39.16.5 マージン内への表示
	`window-max-chars-per-line`	28.3 ウィンドウのサイズ
	`window-min-height`	28.3 ウィンドウのサイズ
	`window-min-height`	28.3 ウィンドウのサイズ
	`window-min-size`	28.3 ウィンドウのサイズ
	`window-min-width`	28.3 ウィンドウのサイズ
	`window-min-width`	28.3 ウィンドウのサイズ
	`window-minibuffer-p`	20.11 ミニバッファーのウィンドウ
	`window-mode-line-height`	28.3 ウィンドウのサイズ
	`window-next-buffers`	28.16 ウィンドウのヒストリー
	`window-next-sibling`	28.2 ウィンドウとフレーム
	`window-parameter`	28.29 ウィンドウのパラメーター
	`window-parameters`	28.29 ウィンドウのパラメーター
	`window-parent`	28.2 ウィンドウとフレーム
	`window-persistent-parameters`	28.29 ウィンドウのパラメーター
	`window-pixel-edges`	28.26 座標とウィンドウ
	`window-pixel-height`	28.3 ウィンドウのサイズ
	`window-pixel-height-before-size-change`	28.3 ウィンドウのサイズ
	`window-pixel-width`	28.3 ウィンドウのサイズ
	`window-pixel-width-before-size-change`	28.3 ウィンドウのサイズ
	`window-point`	28.21 ウィンドウとポイント
	`window-point-insertion-type`	28.21 ウィンドウとポイント
	`window-preserve-size`	28.5 Preserving Window Sizes
	`window-preserved-size`	28.5 Preserving Window Sizes
	`window-preserved-size, a window parameter`	28.29 ウィンドウのパラメーター
	`window-prev-buffers`	28.16 ウィンドウのヒストリー
	`window-prev-sibling`	28.2 ウィンドウとフレーム
	`window-resizable`	28.4 ウィンドウのリサイズ
	`window-resize`	28.4 ウィンドウのリサイズ
	`window-resize-pixelwise`	28.4 ウィンドウのリサイズ
	`window-right-divider-width`	39.15 ウィンドウディバイダー
	`window-scroll-bar-height`	39.14 スクロールバー
	`window-scroll-bar-width`	39.14 スクロールバー
	`window-scroll-bars`	39.14 スクロールバー
	`window-scroll-functions`	28.30 ウィンドウのスクロールと変更のためのフック
	`window-setup-hook`	40.1.2 initファイル
	`window-side, a window parameter`	28.29 ウィンドウのパラメーター
	`window-sides-reversed`	28.19.2 Side Window Options and Functions
	`window-sides-slots`	28.19.2 Side Window Options and Functions
	`window-sides-vertical`	28.19.2 Side Window Options and Functions
	`window-size-change-functions`	28.30 ウィンドウのスクロールと変更のためのフック
	`window-size-fixed`	28.5 Preserving Window Sizes
	`window-slot, a window parameter`	28.29 ウィンドウのパラメーター
	`window-start`	28.22 ウィンドウの開始位置と終了位置
	`window-state-get`	28.28 ウィンドウの構成
	`window-state-put`	28.28 ウィンドウの構成
	`window-swap-states`	28.28 ウィンドウの構成
	`window-system`	39.24 ウィンドウシステム
	`window-system`	39.24 ウィンドウシステム
	`window-system-initialization-alist`	40.1.1 要約: スタートアップ時のアクション順序
	`window-text-pixel-size`	39.10 表示されるテキストのサイズ
	`window-toggle-side-windows`	28.19.2 Side Window Options and Functions
	`window-top-child`	28.2 ウィンドウとフレーム
	`window-total-height`	28.3 ウィンドウのサイズ
	`window-total-size`	28.3 ウィンドウのサイズ
	`window-total-width`	28.3 ウィンドウのサイズ
	`window-tree`	28.2 ウィンドウとフレーム
	`window-use-time`	28.9 ウィンドウの選択
	`window-valid-p`	28.1 Emacsウィンドウの基本概念
	`window-vscroll`	28.24 割り合いによる垂直スクロール
	`windowp`	28.1 Emacsウィンドウの基本概念
	windows, controlling precisely	28.11 バッファーとウィンドウ
	windows, recombining	28.8 ウィンドウの再結合
	`with-case-table`	4.9 caseテーブル
	`with-coding-priority`	33.10.6 単一の操作にたいするコーディングシステムの指定
	`with-connection-local-profiles`	12.14 Connection Local Variables
	`with-current-buffer`	27.2 カレントバッファー
	`with-current-buffer-window`	39.8 一時的な表示
	`with-demoted-errors`	11.6.3.3 エラーを処理するコードの記述
	`with-displayed-buffer-window`	39.8 一時的な表示
	`with-eval-after-load`	16.10 ロードのためのフック
	`with-file-modes`	25.7 ファイルの名前と属性の変更
	`with-help-window`	24.6 ヘルプ関数
	`with-local-quit`	21.11 quit
	`with-mutex`	37.2 Mutexes
	`with-no-warnings`	17.6 コンパイラーのエラー
	`with-output-to-string`	19.5 出力関数
	`with-output-to-temp-buffer`	39.8 一時的な表示
	`with-selected-window`	28.9 ウィンドウの選択
	`with-silent-modifications`	32.19.2 テキストプロパティの変更
	`with-syntax-table`	35.3 構文テーブルの関数
	`with-temp-buffer`	27.2 カレントバッファー
	`with-temp-buffer-window`	39.8 一時的な表示
	`with-temp-file`	25.4 ファイルの書き込み
	`with-temp-message`	39.4.1 エコーエリアへのメッセージの表示
	`with-timeout`	40.11 遅延実行のためのタイマー
	`word-search-backward`	34.1 文字列の検索
	`word-search-backward-lax`	34.1 文字列の検索
	`word-search-forward`	34.1 文字列の検索
	`word-search-forward-lax`	34.1 文字列の検索
	`word-search-regexp`	34.1 文字列の検索
	words in region	30.2.4 テキスト行単位の移動
	`words-include-escapes`	30.2.2 単語単位の移動
	`wrap-prefix`	39.3 切り詰め
	`write-abbrev-file`	36.3 ファイルへのabbrevの保存
	`write-char`	19.5 出力関数
	`write-contents-functions`	25.2 バッファーの保存
	`write-file`	25.2 バッファーの保存
	`write-file-functions`	25.2 バッファーの保存
	`write-region`	25.4 ファイルの書き込み
	`write-region`	25.8 Files and Secondary Storage
	`write-region-annotate-functions`	25.13.3 漸次仕様
	`write-region-inhibit-fsync`	25.4 ファイルの書き込み
	`write-region-post-annotation-function`	25.13.3 漸次仕様
	writing a documentation string	24.1 ドキュメントの基礎
	writing Emacs primitives	E.7 Emacsプリミティブの記述
	writing to files	25.4 ファイルの書き込み
	`wrong-number-of-arguments`	13.2.3 引数リストのその他機能
	`wrong-type-argument`	2.6 型のための述語

X
	X display names	29.2 複数の端末
	X Window System	39.24 ウィンドウシステム
	`x-alt-keysym`	40.16 X11キーシンボルの処理
	`x-alternatives-map`	Appendix G 標準的なキーマップ
	`x-bitmap-file-path`	39.12.1 フェイスの属性
	`x-close-connection`	29.2 複数の端末
	`x-color-defined-p`	29.22 カラー名
	`x-color-values`	29.22 カラー名
	`x-ctrl-keysym`	40.16 X11キーシンボルの処理
	`x-defined-colors`	29.22 カラー名
	`x-display-color-p`	29.25 ディスプレー機能のテスト
	`x-display-list`	29.2 複数の端末
	`x-dnd-known-types`	29.21 ドラッグアンドドロップ
	`x-dnd-test-function`	29.21 ドラッグアンドドロップ
	`x-dnd-types-alist`	29.21 ドラッグアンドドロップ
	`x-double-buffered-p`	29.11 フレームの可視性
	`x-family-fonts`	39.12.10 フォントの照会
	`x-focus-frame`	29.10 入力のフォーカス
	`x-get-resource`	29.24 Xリソース
	`x-gtk-use-system-tooltips`	39.25 Tooltips
	`x-hyper-keysym`	40.16 X11キーシンボルの処理
	`x-list-fonts`	39.12.10 フォントの照会
	`x-meta-keysym`	40.16 X11キーシンボルの処理
	`x-open-connection`	29.2 複数の端末
	`x-parse-geometry`	29.4.4 ジオメトリー
	`x-pointer-shape`	29.19 ポインターの形状
	`x-popup-dialog`	29.18 ダイアログボックス
	`x-popup-menu`	29.17 ポップアップメニュー
	`x-resource-class`	29.24 Xリソース
	`x-resource-name`	29.24 Xリソース
	`x-sensitive-text-pointer-shape`	29.19 ポインターの形状
	`x-server-vendor`	29.25 ディスプレー機能のテスト
	`x-server-version`	29.25 ディスプレー機能のテスト
	`x-setup-function-keys`	Appendix G 標準的なキーマップ
	`x-stretch-cursor`	29.4.3.9 カーソルのパラメーター
	`x-super-keysym`	40.16 X11キーシンボルの処理
	X11 keysyms	40.16 X11キーシンボルの処理
	XBM	39.17.3 XBMイメージ
	XML DOM	32.28.1 Document Object Model
	XPM	39.17.4 XPMイメージ
	xwidget	39.18 Embedded Native Widgets
	`xwidget-buffer`	39.18 Embedded Native Widgets
	`xwidget-info`	39.18 Embedded Native Widgets
	`xwidget-plist`	39.18 Embedded Native Widgets
	`xwidget-query-on-exit-flag`	39.18 Embedded Native Widgets
	`xwidget-resize`	39.18 Embedded Native Widgets
	`xwidget-size-request`	39.18 Embedded Native Widgets
	`xwidget-webkit-execute-script`	39.18 Embedded Native Widgets
	`xwidget-webkit-execute-script-rv`	39.18 Embedded Native Widgets
	`xwidget-webkit-get-title`	39.18 Embedded Native Widgets
	`xwidget-webkit-goto-uri`	39.18 Embedded Native Widgets
	`xwidgetp`	39.18 Embedded Native Widgets

Y
	`y-or-n-p`	20.7 Yes-or-Noによる問い合わせ
	`y-or-n-p-with-timeout`	20.7 Yes-or-Noによる問い合わせ
	`yank`	32.8.4 yankのための関数
	yank suppression	22.12 キーバインディングの変更
	`yank-excluded-properties`	32.8.3 yank
	`yank-handled-properties`	32.8.3 yank
	`yank-pop`	32.8.4 yankのための関数
	`yank-undo-function`	32.8.4 yankのための関数
	yanking and text properties	32.8.3 yank
	yes-or-no questions	20.7 Yes-or-Noによる問い合わせ
	`yes-or-no-p`	20.7 Yes-or-Noによる問い合わせ

Z
	`z-group, a frame parameter`	29.4.3.2 位置のパラメーター
	Z-order	29.12 Raising, Lowering and Restacking Frames
	`zerop`	3.3 数値のための述語
	`zlib-available-p`	32.24 圧縮されたデータの処理
	`zlib-decompress-region`	32.24 圧縮されたデータの処理

Jump to:	" # $ % & ' ( ) * + , - . / 1 2 3 ; < = > ? @ [ \ ] ^ ` \| A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Footnotes

(1)

副文字テーブル(sub-char-tables)に使用される‘#^^’を目にすることがあるかもしれません。

(2)

リストの最後に要素を追加するための、これと完全に同等な方法はありません。listnameをコピーすることにより新しいリストを作成してから、neweltをそのリストの最後に追加する(append listname (list newelt))を使用することができます。すべてのCDRを辿って終端のnilを置き換える、(nconc listname (list newelt))を使用することもできます。コピーも変更も行なわずにリストの先頭に要素を追加するconsと比較してみてください。

1 イントロダクション
- 1.1 注意事項
- 1.2 Lispの歴史
- 1.3 表記について
- 1.4 バージョンの情報
- 1.5 謝辞
2 Lispのデータ型
- 2.1 プリント表現と読み取り構文
- 2.2 コメント
- 2.3 プログラミングの型
- 2.4 編集用の型
- 2.5 循環オブジェクトの読み取り構文
- 2.6 型のための述語
- 2.7 同等性のための述語
3 数値
- 3.1 整数の基礎
- 3.2 浮動小数点数の基礎
- 3.3 数値のための述語
- 3.4 数値の比較
- 3.5 数値の変換
- 3.6 算術演算
- 3.7 丸め処理
- 3.8 ビット演算 on Integers
- 3.9 標準的な数学関数
- 3.10 乱数
4 文字列と文字
- 4.1 文字列と文字の基礎
- 4.2 文字列のための述語
- 4.3 文字列の作成
- 4.4 文字列の変更
- 4.5 文字および文字列の比較
- 4.6 文字および文字列の変換
- 4.7 文字列のフォーマット
- 4.8 Lispでの大文字小文字変換
- 4.9 caseテーブル
5 リスト
- 5.1 リストとコンスセル
- 5.2 リストのための述語
- 5.3 リスト要素へのアクセス
- 5.4 コンスセルおよびリストの構築
- 5.5 リスト変数の変更
- 5.6 既存のリスト構造の変更
- 5.7 集合としてのリストの使用
- 5.8 連想リスト
- 5.9 プロパティリスト
  - 5.9.1 プロパティリストと連想リスト
  - 5.9.2 プロパティリストと外部シンボル
6 シーケンス、配列、ベクター
- 6.1 シーケンス
- 6.2 配列
- 6.3 配列を操作する関数
- 6.4 ベクター
- 6.5 ベクターのための関数
- 6.6 文字テーブル
- 6.7 ブールベクター
- 6.8 オブジェクト用固定長リングの管理
7 Records
- 7.1 Record Functions
- 7.2 Backward Compatibility
8 ハッシュテーブル
- 8.1 ハッシュテーブルの作成
- 8.2 ハッシュテーブルへのアクセス
- 8.3 ハッシュの比較の定義
- 8.4 ハッシュテーブルのためのその他関数
9 シンボル
- 9.1 シンボルの構成要素
- 9.2 シンボルの定義
- 9.3 シンボルの作成とintern
- 9.4 シンボルのプロパティ
  - 9.4.1 シンボルのプロパティへのアクセス
  - 9.4.2 シンボルの標準的なプロパティ
10 評価
- 10.1 評価の概要
- 10.2 フォームの種類
- 10.3 クォート
- 10.4 バッククォート
- 10.5 eval
11 制御構造
- 11.1 順序
- 11.2 条件
  - 11.2.1 パターンマッチングによるcase文
- 11.3 条件の組み合わせ
- 11.4 繰り返し
- 11.5 Generators
- 11.6 非ローカル脱出
12 変数
- 12.1 グローバル変数
- 12.2 変更不可な変数
- 12.3 ローカル変数
- 12.4 When a Variable is Void
- 12.5 グローバル変数の定義
- 12.6 堅牢な変数定義のためのヒント
- 12.7 変数の値へのアクセス
- 12.8 変数の値のセット
- 12.9 Running a function when a variable is changed.
  - 12.9.1 Limitations
- 12.10 変数のバインディングのスコーピングルール
- 12.11 バッファーローカル変数
- 12.12 ファイルローカル変数
- 12.13 ディレクトリーローカル変数
- 12.14 Connection Local Variables
- 12.15 変数のエイリアス
- 12.16 値を制限された変数
- 12.17 ジェネリック変数
  - 12.17.1 setfマクロ
  - 12.17.2 新たなsetfフォーム
13 関数
- 13.1 関数とは?
- 13.2 ラムダ式
- 13.3 関数の命名
- 13.4 関数の定義
- 13.5 関数の呼び出し
- 13.6 関数のマッピング
- 13.7 無名関数
- 13.8 Generic Functions
- 13.9 関数セルの内容へのアクセス
- 13.10 クロージャー
- 13.11 Emacs Lisp関数にたいするアドバイス
- 13.12 関数を陳腐と宣言する
- 13.13 インライン関数Inline Functions
- 13.14 declareフォーム
- 13.15 コンパイラーへの定義済み関数の指示
- 13.16 安全に関数を呼び出せるかどうかの判断
- 13.17 関数に関するその他トピック
14 マクロ
- 14.1 単純なマクロの例
- 14.2 マクロ呼び出しの展開
- 14.3 マクロとバイトコンパイル
- 14.4 マクロの定義
- 14.5 マクロ使用に関する一般的な問題
- 14.6 マクロのインデント
15 カスタマイズ設定
- 15.1 一般的なキーワードアイテム
- 15.2 カスタマイズグループの定義
- 15.3 カスタマイズ変数の定義
- 15.4 カスタマイズ型
- 15.5 カスタマイズの適用
- 15.6 カスタムテーマ
16 ロード
- 16.1 プログラムがロードを行う方法
- 16.2 ロードでの拡張子
- 16.3 ライブラリー検索
- 16.4 非ASCII文字のロード
- 16.5 autoload
  - 16.5.1 When to Use Autoload
- 16.6 多重ロード
- 16.7 名前つき機能
- 16.8 どのファイルで特定のシンボルが定義されているか
- 16.9 アンロード
- 16.10 ロードのためのフック
- 16.11 Emacs Dynamic Modules
17 バイトコンパイル
- 17.1 バイトコンパイル済みコードのパフォーマンス
- 17.2 バイトコンパイル関数
- 17.3 ドキュメント文字列とコンパイル
- 17.4 個別関数のダイナミックロード
- 17.5 コンパイル中の評価
- 17.6 コンパイラーのエラー
- 17.7 バイトコード関数オブジェクト
- 17.8 逆アセンブルされたバイトコード
18 Lispプログラムのデバッグ
- 18.1 Lispデバッガ
- 18.2 Edebug
- 18.3 無効なLisp構文のデバッグ
  - 18.3.1 過剰な開カッコ
  - 18.3.2 過剰な閉カッコ
- 18.4 カバレッジテスト
- 18.5 プロファイリング
19 Lispオブジェクトの読み取りとプリント
- 19.1 読み取りとプリントの概念
- 19.2 入力ストリーム
- 19.3 入力関数
- 19.4 出力ストリーム
- 19.5 出力関数
- 19.6 出力に影響する変数
20 ミニバッファー
- 20.1 ミニバッファーの概念
- 20.2 ミニバッファーでのテキスト文字列の読み取り
- 20.3 ミニバッファーでのLispオブジェクトの読み取り
- 20.4 ミニバッファーのヒストリー
- 20.5 入力の初期値
- 20.6 補完
- 20.7 Yes-or-Noによる問い合わせ
- 20.8 複数のY-or-Nの問い合わせ
- 20.9 パスワードの読み取り
- 20.10 ミニバッファーのコマンド
- 20.11 ミニバッファーのウィンドウ
- 20.12 ミニバッファーのコンテンツ
- 20.13 再帰的なミニバッファー
- 20.14 ミニバッファー、その他の事項
21 コマンドループ
- 21.1 コマンドループの概要
- 21.2 コマンドの定義
- 21.3 interactiveな呼び出し
- 21.4 interactiveな呼び出しの区別
- 21.5 コマンドループからの情報
- 21.6 コマンド後のポイントの調整
- 21.7 入力イベント
- 21.8 入力の読み取り
- 21.9 スペシャルイベント
- 21.10 時間の経過や入力の待機
- 21.11 quit
- 21.12 プレフィクスコマンド引数
- 21.13 再帰編集
- 21.14 コマンドの無効化
- 21.15 コマンドのヒストリー
- 21.16 キーボードマクロ
22 キーマップ
- 22.1 キーシーケンス
- 22.2 キーマップの基礎
- 22.3 キーマップのフォーマット
- 22.4 キーマップの作成
- 22.5 継承とキーマップ
- 22.6 プレフィクスキー
- 22.7 アクティブなキーマップ
- 22.8 アクティブなキーマップの検索
- 22.9 アクティブなキーマップの制御
- 22.10 キーの照合
- 22.11 キー照合のための関数
- 22.12 キーバインディングの変更
- 22.13 コマンドのリマップ
- 22.14 イベントシーケンス変換のためのキーマップ
  - 22.14.1 通常のキーマップとの対話
- 22.15 キーのバインドのためのコマンド
- 22.16 キーマップのスキャン
- 22.17 メニューキーアップ
23 メジャーモードとマイナーモード
- 23.1 フック
  - 23.1.1 フックの実行
  - 23.1.2 フックのセットSetting Hooks
- 23.2 メジャーモード
- 23.3 マイナーモード
- 23.4 モードラインのフォーマット
- 23.5 Imenu
- 23.6 Font Lockモード
- 23.7 コードの自動インデント
  - 23.7.1 SMIE: 無邪気なインデントエンジン
- 23.8 Desktop Saveモード
24 ドキュメント
- 24.1 ドキュメントの基礎
- 24.2 ドキュメント文字列へのアクセス
- 24.3 ドキュメント内でのキーバインディングの置き換え
- 24.4 Text Quoting Style
- 24.5 ヘルプメッセージの文字記述
- 24.6 ヘルプ関数
25 ファイル
- 25.1 ファイルのvisit
  - 25.1.1 ファイルをvisitする関数
  - 25.1.2 visitのためのサブルーチン
- 25.2 バッファーの保存
- 25.3 ファイルの読み込み
- 25.4 ファイルの書き込み
- 25.5 ファイルのロック
- 25.6 ファイルの情報
- 25.7 ファイルの名前と属性の変更
- 25.8 Files and Secondary Storage
- 25.9 ファイルの名前
- 25.10 ディレクトリーのコンテンツ
- 25.11 ディレクトリーの作成・コピー・削除
- 25.12 特定のファイル名の“Magic”の作成
- 25.13 ファイルのフォーマット変換
26 バックアップと自動保存
- 26.1 ファイルのバックアップ
- 26.2 自動保存
- 26.3 リバート
27 バッファー
- 27.1 バッファーの基礎
- 27.2 カレントバッファー
- 27.3 バッファーの名前
- 27.4 バッファーのファイル名
- 27.5 バッファーの変更
- 27.6 バッファーの変更 Time
- 27.7 読み取り専用のバッファー
- 27.8 バッファーリスト
- 27.9 バッファーの作成
- 27.10 バッファーのkill
- 27.11 インダイレクトバッファー
- 27.12 2つのバッファー間でのテキストの交換
- 27.13 バッファーのギャップ
28 ウィンドウ
- 28.1 Emacsウィンドウの基本概念
- 28.2 ウィンドウとフレーム
- 28.3 ウィンドウのサイズ
- 28.4 ウィンドウのリサイズ
- 28.5 Preserving Window Sizes
- 28.6 ウィンドウの分割
- 28.7 ウィンドウの削除
- 28.8 ウィンドウの再結合
- 28.9 ウィンドウの選択
- 28.10 ウィンドウのサイクル順
- 28.11 バッファーとウィンドウ
- 28.12 ウィンドウ内のバッファーへの切り替え
- 28.13 表示するウィンドウの選択
- 28.14 display-bufferにたいするアクション関数
- 28.15 バッファー表示の追加オプション
- 28.16 ウィンドウのヒストリー
- 28.17 専用のウィンドウ
- 28.18 ウィンドウのquit
- 28.19 Side Windows
  - 28.19.1 Displaying Buffers in Side Windows
  - 28.19.2 Side Window Options and Functions
  - 28.19.3 Frame Layouts with Side Windows
- 28.20 Atomic Windows
- 28.21 ウィンドウとポイント
- 28.22 ウィンドウの開始位置と終了位置
- 28.23 テキスト的なスクロール
- 28.24 割り合いによる垂直スクロール
- 28.25 水平スクロール
- 28.26 座標とウィンドウ
- 28.27 Mouse Window Auto-selection
- 28.28 ウィンドウの構成
- 28.29 ウィンドウのパラメーター
- 28.30 ウィンドウのスクロールと変更のためのフック
29 フレーム
- 29.1 フレームの作成
- 29.2 複数の端末
- 29.3 Frame Geometry
  - 29.3.1 Frame Layout
  - 29.3.2 Frame Font
  - 29.3.3 Frame Position
  - 29.3.4 Frame Size
  - 29.3.5 Implied Frame Resizing
- 29.4 フレームのパラメーター
  - 29.4.1 フレームパラメーターへのアクセス
  - 29.4.2 フレームの初期パラメーター
  - 29.4.3 ウィンドウフレームパラメーター
  - 29.4.4 ジオメトリー
- 29.5 端末のパラメーター
- 29.6 フレームのタイトル
- 29.7 フレームの削除
- 29.8 すべてのフレームを探す
- 29.9 ミニバッファーとフレーム
- 29.10 入力のフォーカス
- 29.11 フレームの可視性
- 29.12 Raising, Lowering and Restacking Frames
- 29.13 フレーム構成
- 29.14 Child Frames
- 29.15 マウスの追跡
- 29.16 マウスの位置
- 29.17 ポップアップメニュー
- 29.18 ダイアログボックス
- 29.19 ポインターの形状
- 29.20 ウィンドウシステムによる選択
- 29.21 ドラッグアンドドロップ
- 29.22 カラー名
- 29.23 テキスト端末のカラー
- 29.24 Xリソース
- 29.25 ディスプレー機能のテスト
30 ポジション
- 30.1 ポイント
- 30.2 モーション
- 30.3 エクスカーション
- 30.4 ナローイング
31 マーカー
- 31.1 マーカーの概要
- 31.2 マーカーのための述語
- 31.3 マーカーを作成する関数
- 31.4 マーカーからの情報
- 31.5 Marker 挿入タイプ
- 31.6 マーカー位置の移動
- 31.7 マーク
- 31.8 リージョン
32 テキスト
- 32.1 ポイント周辺のテキストを調べる
- 32.2 バッファーのコンテンツを調べる
- 32.3 テキストの比較
- 32.4 テキストの挿入
- 32.5 ユーザーレベルの挿入コマンド
- 32.6 テキストの削除
- 32.7 ユーザーレベルの削除コマンド
- 32.8 killリング
  - 32.8.1 killリングの概念
  - 32.8.2 killリングのための関数
  - 32.8.3 yank
  - 32.8.4 yankのための関数
  - 32.8.5 低レベルのkillリング
  - 32.8.6 killリングの内部
- 32.9 アンドゥ
- 32.10 アンドゥリストの保守
- 32.11 fill
- 32.12 fillのマージン
- 32.13 Adaptive Fillモード
- 32.14 オートfill
- 32.15 テキストのソート
- 32.16 列を数える
- 32.17 インデント
  - 32.17.1 インデント用のプリミティブ
  - 32.17.2 メジャーモードが制御するインデント
  - 32.17.3 リージョン全体のインデント
  - 32.17.4 前行に相対的なインデント
  - 32.17.5 Adjustable Tab Stops
  - 32.17.6 インデントにもとづくモーションコマンド
- 32.18 大文字小文字の変更
- 32.19 テキストのプロパティ
  - 32.19.1 テキストプロパティを調べる
  - 32.19.2 テキストプロパティの変更
  - 32.19.3 テキストプロパティの検索関数
  - 32.19.4 特殊な意味をもつプロパティ
  - 32.19.5 フォーマットされたテキストプロパティ
  - 32.19.6 テキストプロパティの粘着性
  - 32.19.7 テキストプロパティのlazyな計算
  - 32.19.8 クリック可能なテキストの定義
  - 32.19.9 フィールドの定義と使用
  - 32.19.10 なぜテキストプロパティはインターバルではないのか
- 32.20 文字コードの置き換え
- 32.21 レジスター
- 32.22 テキストの交換
- 32.23 Replacing Buffer Text
- 32.24 圧縮されたデータの処理
- 32.25 Base 64エンコーディング
- 32.26 チェックサムとハッシュ
- 32.27 GnuTLS Cryptography
  - 32.27.1 Format of GnuTLS Cryptography Inputs
  - 32.27.2 GnuTLS Cryptographic Functions
- 32.28 HTMLとXMLの解析
  - 32.28.1 Document Object Model
- 32.29 グループのアトミックな変更
- 32.30 フックの変更
33 非ASCII文字
- 33.1 テキストの表現方法
- 33.2 マルチバイト文字の無効化
- 33.3 テキスト表現の変換
- 33.4 表現の選択
- 33.5 文字コード
- 33.6 文字のプロパティ
- 33.7 文字セット
- 33.8 文字セットのスキャン
- 33.9 文字の変換
- 33.10 コーディングシステム
- 33.11 入力メソッド
- 33.12 locale
34 検索とマッチング
- 34.1 文字列の検索
- 34.2 検索と大文字小文字
- 34.3 正規表現
- 34.4 正規表現の検索
- 34.5 POSIX正規表現の検索
- 34.6 マッチデータ
- 34.7 検索と置換
- 34.8 編集で使用される標準的な正規表現
35 構文テーブル
- 35.1 構文テーブルの概念
- 35.2 構文記述子
  - 35.2.1 構文クラスのテーブル
  - 35.2.2 構文フラグ
- 35.3 構文テーブルの関数
- 35.4 構文プロパティ
- 35.5 モーションと構文
- 35.6 式のパース
- 35.7 構文テーブルの内部
- 35.8 カテゴリー
36 abbrevとabbrev展開
- 36.1 abbrevテーブル
- 36.2 abbrevの定義
- 36.3 ファイルへのabbrevの保存
- 36.4 略語の照会と展開
- 36.5 標準的なabbrevテーブル
- 36.6 abbrevプロパティー
- 36.7 abbrevテーブルのプロパティー
37 Threads
- 37.1 Basic Thread Functions
- 37.2 Mutexes
- 37.3 Condition Variables
38 プロセス
- 38.1 サブプロセスを作成する関数
- 38.2 shell引数
- 38.3 同期プロセスの作成
- 38.4 非同期プロセスの作成
- 38.5 プロセスの削除
- 38.6 プロセスの情報
- 38.7 プロセスへの入力の送信
- 38.8 プロセスへのシグナルの送信
- 38.9 プロセスからの出力の受信
  - 38.9.1 プロセスのバッファー
  - 38.9.2 プロセスのフィルター関数
  - 38.9.3 プロセス出力のデコード
  - 38.9.4 プロセスからの出力を受け入れる
  - 38.9.5 Processes and Threads
- 38.10 センチネル: プロセス状態の変更の検知
- 38.11 exit前の問い合わせ
- 38.12 別のプセスへのアクセス
- 38.13 トランザクションキュー
- 38.14 ネットワーク接続
- 38.15 ネットワークサーバー
- 38.16 データグラム
- 38.17 低レベルのネットワークアクセス
  - 38.17.1 make-network-process
  - 38.17.2 ネットワークのオプション
  - 38.17.3 ネットワーク機能の可用性のテスト
- 38.18 その他のネットワーク機能
- 38.19 シリアルポートとの対話
- 38.20 バイト配列のpackとunpack
  - 38.20.1 データレイアウトの記述
  - 38.20.2 バイトのunpackとpackのための関数
  - 38.20.3 バイトのunpackとpackの例
39 Emacsのディスプレー表示
- 39.1 スクリーンのリフレッシュ
- 39.2 強制的な再表示
- 39.3 切り詰め
- 39.4 エコーエリア
  - 39.4.1 エコーエリアへのメッセージの表示
  - 39.4.2 処理の進捗レポート
  - 39.4.3 *Messages*へのメッセージのロギング
  - 39.4.4 エコーエリアのカスタマイズ
- 39.5 警告のレポート
  - 39.5.1 警告の基礎
  - 39.5.2 警告のための変数
  - 39.5.3 警告のためのオプション
  - 39.5.4 遅延された警告
- 39.6 不可視のテキスト
- 39.7 選択的な表示
- 39.8 一時的な表示
- 39.9 オーバーレイ
  - 39.9.1 オーバーレイの管理
  - 39.9.2 オーバーレイのプロパティ
  - 39.9.3 オーバーレイにたいする検索
- 39.10 表示されるテキストのサイズ
- 39.11 行の高さ
- 39.12 フェイス
  - 39.12.1 フェイスの属性
  - 39.12.2 フェイスの定義
  - 39.12.3 フェイス属性のための関数
  - 39.12.4 フェイスの表示
  - 39.12.5 フェイスのリマップ
  - 39.12.6 フェイスを処理するための関数
  - 39.12.7 フェイスの自動割り当て
  - 39.12.8 基本的なフェイス
  - 39.12.9 フォントの選択
  - 39.12.10 フォントの照会
  - 39.12.11 フォントセット
  - 39.12.12 低レベルのフォント表現
- 39.13 フリンジ
  - 39.13.1 フリンジのサイズと位置
  - 39.13.2 フリンジのインジケーター
  - 39.13.3 フリンジのカーソルFringe Cursors
  - 39.13.4 フリンジのビットマップ
  - 39.13.5 フリンジビットマップのカスタマイズ
  - 39.13.6 オーバーレイ矢印
- 39.14 スクロールバー
- 39.15 ウィンドウディバイダー
- 39.16 displayプロパティ
  - 39.16.1 テキストを置換するディスプレー仕様
  - 39.16.2 スペースの指定
  - 39.16.3 スペースにたいするピクセル指定
  - 39.16.4 その他のディスプレー仕様
  - 39.16.5 マージン内への表示
- 39.17 イメージ
  - 39.17.1 イメージのフォーマット
  - 39.17.2 イメージのディスクリプタ
  - 39.17.3 XBMイメージ
  - 39.17.4 XPMイメージ
  - 39.17.5 ImageMagickイメージ
  - 39.17.6 SVG Images
  - 39.17.7 その他のイメージタイプ
  - 39.17.8 イメージの定義
  - 39.17.9 イメージの表示
  - 39.17.10 マルチフレームのイメージ
  - 39.17.11 イメージキャッシュ
- 39.18 Embedded Native Widgets
- 39.19 ボタン
  - 39.19.1 ボタンのプロパティ
  - 39.19.2 ボタンのタイプ
  - 39.19.3 ボタンの作成
  - 39.19.4 ボタンの操作
  - 39.19.5 ボタンのためのバッファーコマンド
- 39.20 抽象的なディスプレー
  - 39.20.1 抽象ディスプレーの関数
  - 39.20.2 抽象ディスプレーの例
- 39.21 カッコの点滅
- 39.22 文字の表示
  - 39.22.1 通常の表示の慣習
  - 39.22.2 ディスプレーテーブル
  - 39.22.3 アクティブなディスプレーテーブル
  - 39.22.4 グリフ
  - 39.22.5 グリフ文字の表示
- 39.23 ビープ
- 39.24 ウィンドウシステム
- 39.25 Tooltips
- 39.26 双方向テキストの表示
40 オペレーティングシステムのインターフェース
- 40.1 Emacsのスタートアップ
  - 40.1.1 要約: スタートアップ時のアクション順序
  - 40.1.2 initファイル
  - 40.1.3 端末固有の初期化
  - 40.1.4 コマンドライン引数
- 40.2 Emacsからの脱出
  - 40.2.1 Emacsのkill
  - 40.2.2 Emacsのサスペンド
- 40.3 オペレーティングシステムの環境
- 40.4 ユーザーの識別
- 40.5 時刻
- 40.6 Time Zone Rules
- 40.7 時刻の変換
- 40.8 時刻のパースとフォーマット
- 40.9 プロセッサーの実行時間
- 40.10 時間の計算
- 40.11 遅延実行のためのタイマー
- 40.12 アイドルタイマー
- 40.13 端末の入力
  - 40.13.1 入力のモード
  - 40.13.2 入力の記録
- 40.14 端末の出力
- 40.15 サウンドの出力
- 40.16 X11キーシンボルの処理
- 40.17 batchモード
- 40.18 セッションマネージャー
- 40.19 デスクトップ通知
- 40.20 ファイル変更による通知
- 40.21 動的にロードされるライブラリー
- 40.22 Security Considerations
41 配布用 Lispコードの準備
- 41.1 パッケージ化の基礎
- 41.2 単純なパッケージ
- 41.3 複数ファイルのパッケージ
- 41.4 パッケージアーカイブの作成と保守
Appendix A Emacs 25 Antinews
- A.1 Old Lisp Features in Emacs 25
Appendix B GNU Free Documentation License
Appendix C GNU General Public License
Appendix D ヒントと規約
- D.1 Emacs Lispコーディングの慣習
- D.2 キーバインディングの慣習
- D.3 Emacsプログラミングのヒント
- D.4 コンパイル済みコードを高速化ためのヒント
- D.5 コンパイラー警告を回避するためのヒント
- D.6 ドキュメント文字列のヒント
- D.7 コメント記述のヒント
- D.8 Emacsライブラリーのヘッダーの慣習
Appendix E GNU Emacsの内部
- E.1 Emacsのビルド
- E.2 純粋ストレージ
- E.3 ガーベージコレクション
- E.4 Stack-allocated Objects
- E.5 メモリー使用量
- E.6 C方言
- E.7 Emacsプリミティブの記述
- E.8 オブジェクトの内部
- E.9 Cの整数型
Appendix F 標準的なエラー
Appendix G 標準的なキーマップ
Appendix H 標準的なフック
Index

Short Table of Contents

1 イントロダクション
2 Lispのデータ型
3 数値
4 文字列と文字
5 リスト
6 シーケンス、配列、ベクター
7 Records
8 ハッシュテーブル
9 シンボル
10 評価
11 制御構造
12 変数
13 関数
14 マクロ
15 カスタマイズ設定
16 ロード
17 バイトコンパイル
18 Lispプログラムのデバッグ
19 Lispオブジェクトの読み取りとプリント
20 ミニバッファー
21 コマンドループ
22 キーマップ
23 メジャーモードとマイナーモード
24 ドキュメント
25 ファイル
26 バックアップと自動保存
27 バッファー
28 ウィンドウ
29 フレーム
30 ポジション
31 マーカー
32 テキスト
33 非ASCII文字
34 検索とマッチング
35 構文テーブル
36 abbrevとabbrev展開
37 Threads
38 プロセス
39 Emacsのディスプレー表示
40 オペレーティングシステムのインターフェース
41 配布用 Lispコードの準備
Appendix A Emacs 25 Antinews
Appendix B GNU Free Documentation License
Appendix C GNU General Public License
Appendix D ヒントと規約
Appendix E GNU Emacsの内部
Appendix F 標準的なエラー
Appendix G 標準的なキーマップ
Appendix H 標準的なフック
Index

About This Document

This document was generated on October 24, 2019 using texi2any.

The buttons in the navigation panels have the following meaning:

Button	Name	Go to	From 1.2.3 go to
[ << ]	FastBack	Beginning of this chapter or previous chapter	1
[ < ]	Back	Previous section in reading order	1.2.2
[ Up ]	Up	Up section	1.2
[ > ]	Forward	Next section in reading order	1.2.4
[ >> ]	FastForward	Next chapter	2
[Top]	Top	Cover (top) of document
[Contents]	Contents	Table of contents
[Index]	Index	Index
[ ? ]	About	About (help)

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

1. Section One
- 1.1 Subsection One-One
  - ...
- 1.2 Subsection One-Two
  - 1.2.1 Subsubsection One-Two-One
  - 1.2.2 Subsubsection One-Two-Two
  - 1.2.3 Subsubsection One-Two-Three <== Current Position
  - 1.2.4 Subsubsection One-Two-Four
- 1.3 Subsection One-Three
  - ...
- 1.4 Subsection One-Four

This document was generated on October 24, 2019 using texi2any.

2.3.6.1 ボックスダイアグラムとしてのリストの描写		リストの図解。
2.3.6.2 ドットペア表記		コンスセルの一般的な構文。
2.3.6.3 連想リスト型		特別に構築されるリスト。

13.11.1 アドバイスを操作するためのプリミティブ		アドバイスを扱うプリミティブ。
13.11.2 名前つき関数にたいするアドバイス		名前つき関数のアドバイス。
13.11.3 Ways to compose advice
13.11.4 古いdefadviceを使用するコードの改良		古いdefadviceを使用したコードの改良。

21.2.1 `interactive`の使用		`interactive`にたいする一般的なルール。
21.2.2 `interactive`にたいするコード文字		さまざまな方法で引数を読み取る標準的な文字のコード。
21.2.3 `interactive`の使用例		インタラクティブ引数を読み取る方法の例。
21.2.4 コマンド候補からの選択

25.13.1 概要		`insert-file-contents`と`write-region`
25.13.2 ラウンドトリップ仕様		`format-alist`の使用。
25.13.3 漸次仕様		非ペアー変換の指定。

38.17.1 `make-network-process`		`make-network-process`の使用。
38.17.2 ネットワークのオプション		更なるネットワーク接続の制御。
38.17.3 ネットワーク機能の可用性のテスト		使用中マシン上で動作するネットワーク機能を判断する。

GNU Emacs Lisp Reference Manual

For Emacs Version 26.1

Revision 3.1, October 2014

Emacs Lisp

1 イントロダクション

1.1 注意事項

1.2 Lispの歴史

1.3 表記について

1.3.1 用語について

1.3.2 nilとt

1.3.3 評価の表記

1.3.4 プリントの表記

1.3.5 エラーメッセージ

1.3.6 バッファーテキストの表記

1.3.7 説明のフォーマット

1.3.7.1 関数の説明例

1.3.7.2 変数の説明例

1.4 バージョンの情報

1.5 謝辞

2 Lispのデータ型

2.1 プリント表現と読み取り構文

2.2 コメント

2.3 プログラミングの型

2.3.1 整数型

2.3.2 浮動小数点数型

2.3.3 文字型

2.3.3.1 基本的な文字構文

2.3.3.2 一般的なエスケープ構文

2.3.3.3 コントロール文字構文

2.3.3.4 メタ文字構文

2.3.3.5 その他の文字修飾ビット

2.3.4 シンボル型

2.3.5 シーケンス型

2.3.6 コンスセルとリスト型

2.3.6.1 ボックスダイアグラムとしてのリストの描写

2.3.6.2 ドットペア表記

2.3.6.3 連想リスト型

2.3.7 配列型

2.3.8 文字列型

2.3.8.1 文字列の構文

2.3.8.2 文字列内の非ASCII文字

2.3.8.3 文字列内の非プリント文字

2.3.8.4 文字列内のテキストプロパティ

2.3.9 ベクター型

2.3.10 文字テーブル型

2.3.11 ブールベクター型

2.3.12 ハッシュテーブル型

2.3.13 関数型

2.3.14 マクロ型

2.3.15 プリミティブ関数型

2.3.16 バイトコード関数型

2.3.17 Record Type

2.3.18 Type Descriptors

2.3.19 autoload型

2.3.20 Finalizer Type

2.4 編集用の型

2.4.1 バッファー型

2.4.2 マーカー型

2.4.3 ウィンドウ型

2.4.4 フレーム型

2.4.5 端末型

2.4.6 ウィンドウ構成型

2.4.7 フレーム構成型

2.4.8 プロセス型

2.4.9 Thread Type

2.4.10 Mutex Type

2.4.11 Condition Variable Type

2.4.12 ストリーム型

2.4.13 キーマップ型

2.4.14 オーバーレイ型

2.4.15 フォント型

2.5 循環オブジェクトの読み取り構文

2.6 型のための述語

2.7 同等性のための述語

3 数値

3.1 整数の基礎

3.2 浮動小数点数の基礎

3.3 数値のための述語

3.4 数値の比較

3.5 数値の変換

1.3.2 `nil`と`t`

5.6.1 `setcar`によるリスト要素の変更